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The FCC Wants You to Know . . . 

This equipment generates and uses radio frequency energy. If not installed and used prop- 
erly, that is, in strict accordance with the manufacturer's instructions, it may cause interfer- 
ence to radio and television reception. 

It has been type tested and found to comply with the limits for a Class B computing 
device in accordance with the specifications in Subpart J of Part 15 of FCC Rules, which are 
designed to provide reasonable protection against such interference in a residential instal- 
lation. However, there is no guarantee that interference will not occur in a particular 
installation. 

If this equipment does cause interference to radio or television reception, which can be 
determined by turning the equipment off and on, the user is encouraged to try to correct the 
interference by one or more of the following measures: 

• Reorient the receiving antenna 

• Relocate the computer with respect to the receiver 

• Move the computer away from the receiver 

• Plug the computer into a different outlet so that computer and receiver are on different 
branch circuits. 

If necessary, you should consult the dealer or an experienced radio/television technician for 
additional suggestions. You may find the following booklet prepared by the Federal Com- 
munications Commission helpful: How to Identify and Resolve Radio-TV Interference 
Problems. 

This booklet is available from the US Government Printing Office, Washington, DC 
20402, Stock No. 004-000-00345-4. 



Warning 



This equipment has been certified to comply with the limits for a Class B computing device, 
pursuant to Subpart J of Part 15 of FCC Rules. Only peripherals (computer input/output 
devices, terminals, printers, etc.) certified to comply with the Class B limits may be attached 
to this computer. Operation with non-certified peripherals is likely to result in interference to 
radio and TV reception. 
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OWNER'S MANUAL 




To Our Customers 



Congratulations on your purchase of the Model III Disk System. We think it's a 
valuable tool which will save you work as well as give you hours of enjoyment 
(or maybe both at once). You'll have all the power of the non-disk Model III, 
plus the following features: 

• Your Computer can now be controlled by trsdos Co] \ the powerful trs-80 Disk 
Operating System, trsdos is included on a diskette with the Disk System. 

• Using trsdos, you can run a wide variety of programs, such as the Disk basic 
interpreter included on the trsdos diskette. 

• Each "system" diskette has approximately 126,720 bytes of storage available 
for your own programs and data; each "data" diskette has 178,944 bytes 
available. 

• You can load and save data at the approximate rate of 250,000 bits per second. 

• Your system can continue to grow in power and convenience. When Radio 
Shack issues improvements and enhancements to the system programs, you 
can "install" them simply by obtaining a new release of the trsdos diskette. 

Model III Manuals 

Publications related to the use of the Model III Disk System; 

1 . Model 111 Disk System Owner s Manual (this manual). We 1 11 call it the "Disk 
Manual" for short. 

2. Model HI Disk System Quick Reference Card. 

3. Model III Operation and basic Language Reference Manual, the "Model III 
Manual" for short. 

4. Model HI basic Quick Reference Card, 

For Disk Operation; 

This Disk Manual supplements the Model III Manual. Use the Disk Manual as 
the primary source of information; we'll tell you when to refer to the non-disk 
Model III Manual. 

For Non-Disk Operation: 

To use the Computer as a non-disk system, all you need is the Model III 
Manual. 



For Programming Information: 

The Model III Manual contains most of the programming information, except 
that which pertains to disk input/output. In this manual, we will assume that you 




TRS-80 MODEL III DISK SYSTEM 



are familiar with the basic programming definitions and details given in the 
Model III Manual. 



About This Manual 

The Model III Disk System is intended for use by novices as well as 
experienced computer operators and programmers. In designing and writing this 
Disk Manual, we've tried to define and satisfy the needs of both groups: 

♦ Novices who might prefer a sequential presentation which emphasizes 
procedures and explains the purpose of various features. 

• Experienced users who might prefer a more analytical presentation which 
makes it easy to find specific information. 

In this manual, you'll find information that should satisfy your needs, whichever 
group you might belong to. 

The ''Sample Sessions" are especially geared for novices, while the Technical 
Information chapters are for the more experienced users. 

Keep in mind, however, that it isn't necessary to read the entire manual to 
operate the Disk System. If you are only interested in Disk basic, for example, 
read the Operation section of this book and then turn directly to the Disk basic 
section. You can then go back to the trsdos section when you need to. 

Special Terms 

Even in the non-technical sections of this manual, we've had to use numerous 
special terms. Rather than scattering and repeating definitions throughout the 
book, we have used the following convention which we hope you'll find 
helpful. 

Special terms which are fully defined in another part of the manual are printed in 
boldface. Look up the word or phrase in the Index; this will tell you where the 
word is fully defined. 
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Installation 



First set up the Computer according to the instructions in the Model III Manual. 

If you have a one- or two-drive system, installation is now complete. The built- 
in drives should be ready for use. 

If you have a three- or four-drive system, you need to connect the external 
drives. 



External Disk Drives 

The two external drives are not interchangeable. They have different Radio 
Shack Catalog Numbers and a few internal differences. 



First External Drive Purchased 
(Includes Cable) 

Second External Drive Purchased 



System 
Name 

"Drive 2/3' 



"Drive 2" 



Catalog 
Number 

26-1164 



26-1161 



The 26- 1 164 drive may be used as Drive 2 or 3, depending on the number of 
drives in the system, In a three-drive system, it is always Drive 2 (the last 
drive). In a four-drive system, it is always Drive 3 (again, the last drive). 

The 26-1 161 drive may only be used in a four-drive system, in which it must be 
Drive 2. 

1 . Locate the flat "ribbon" cable that was included with the 26-1 164 drive. 
Notice that it has a single plug on one end, and two plugs clustered at the 
other end. See Figure 1 for plug labels. 

2. Connect the solitary "Computer" plug to the Disk Expansion Jack on the 
bottom rear of the Computer. See Figure 2, 

3. Now refer to Figure 3. Connect the external drive(s) to the other end of the 
cable, as follows: 

3- A. If you have one external drive (26-1 164); 

Connect it to the "Drive 2" plug near the middle of the ribbon cable. 

3-B. If you have two external drives (26-1 164 and 26-1 161): 

Connect the 26-1 164 to the "Drive 3" plug on the end of the cable. 
Connect the 26-1 161 to the "Drive 2" plug near the middle of the cable. 

4. Plug the external drive(s) into an appropriate source of ac power. Power 
requirements are specified on the unit and in the specifications given in this 
manual. 



You are now ready to start the Disk System. 
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Computer Plug 



Drive 3 Plug 




Figure 1. External Disk Cable with Plugs Labeled. 




Figure 2. Connection of the External Disk Cable to the Model III. 
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MINI-DISK (REAR VIEW) 



Attach the plug so the cable exits 
toward the rear of the Computer. 




EDGE CARD PLUGS GUIDE PIN 



GUIDE SLOT ■ 



Figure 3. Connection of external disk drives. 
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Operation 



First, take a few minutes to become familiar with the various elements of your 
Disk System. Refer to Figures 4 and 5, This is very important. If you try to use 
the Computer without having a little background information, you could damage 
a diskette. 




Figure 4. The Model III Disk System with External Drives (optional/extra). 



; Drive 0. The trsdos "system diskette" goes 
in this drive. 

: Drives 1, 2, and 3. These drives may 
contain "data diskettes." Data diskettes are 
described briefly in this chapter. 

Drive Select led. When a drive is being 
accessed, its led lights up. 

) Drive Door. To insert or remove a diskette, 
open this door. Never remove a diskette 
while the led is lit, or while the diskette 
contains open files. 



CD Reset Button. When you press this button, 

the Computer will attempt to load the 
operating system software from Drive 0. The 
trsdos diskette should be in Drive when 
you press this button. 

© Power Switch. All drives shouid be empty 
when you turn the Computer on or off. 
Otherwise, the information on the diskettes 
could be destroyed. 




Figure 5. A Diskette. (Catalog Number 26-305, 26-405, or 26-406) 



© Storage Envelope. While a diskette is not in 
use, keep it here. 

© Write Protect Notch. When this is covered, 
the disk-drives cannot write (change infor- 
mation) on the diskette, Do not pinch the tab 
into the notch when you apply it. If the tab 
becomes indented, the disk drive may not 
sense that the disk is write-protected. Leave 
the notch uncovered if you want to save or 
change information on the diskette. 

<D Jacket. The diskette is permanently seated 
inside this protective jacket. Do not attempt 
to remove it. 



© Read/Write Window. The disk drive 
accesses the diskette surface through this 
window. Don't touch the diskette surface. 

CD Label. To write on this label, use only a felt- 
tipped pen. Any other writing implement 
might damage the diskette. 



Diskettes 



In general, handle diskettes carefully, using the same precautions you use with 
tape cassettes and high-fidelity records. A small indentation, dust particle, or 
scratch can render all or part of a diskette unreadable— permanently. 

• Keep the diskette in its storage envelope whenever it is not in one of the 
drives. 

• Do not place a diskette in the drive while you are turning the system on or off. 

• Keep diskettes away from magnetic fields (transformers, AC motors, magnets, 
tvs, radios, etc.). Strong magnetic fields will erase data stored on a diskette. 




TRS-80 MODEL III DISK SYSTEM 



• Handle diskettes by the jacket only. Do not touch any of the exposed surfaces. 
Don't try to wipe or clean the diskette surface; it scratches easily. 

• Keep diskettes out of direct sunlight and away from heat. 

• Avoid contamination of diskettes with cigarette ashes, dust or other particles. 

• Do not write directly on the diskette jacket with a hard point device such as a 
ball point pen or lead pencil; use a felt tip pen only. 

• Store diskettes in a vertical file folder on a shelf where they are protected from 
pressure to their sides (just as phono records are stored). 

• In very dusty environments, you may need to provide filtered air to the 
computer room. 

Tips on Labeling Diskettes 

Each diskette has a permanent label on its jacket. This label is for "vital 
statistics" that will never change. For example, to help keep track of diskettes, 
it's a good idea to assign a unique number to each diskette. Write such a number 
on the permanent label. You might also put your name on the diskette, and 
record the date when the diskette was first put into use. Remember, use only a 
felt tip pen for marking. 

This fc 'permanent 1 ' label is not a good place to record the contents of the diskette 
since that will change, and you don't want to be erasing or scratching out 
information from this label. 



System Start-Up 



1 . Turn all peripherals on. 

2. Turn the Computer on. Wait until all disk drive motors stop. 

3. Locate the trsdos diskette that was supplied with the Disk System. Insert it 
into Drive 0, with the label side facing up and the read/write window 
pointing into the drive slot. See Figure 6. 

4. When the diskette is fully inserted, close the drive door. 

5. Press reset. The Computer should now load trsdos and begin the start-up 
dialog described in the next section. 

If nothing happens on the Display, or if the message: DISKETTE? or NOT A 
SYSTEM DISK is displayed, check the following: 

• Are you using a trsdos "system" diskette? 

• Is the diskette properly inserted into Drive 0? 

• If external drives are present, are they properly connected and turned on? 
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Figure 6. Inserting a Diskette. 

If you can't find the problem, refer to the Troubleshooting and Maintenance 
chapter for further suggestions. 



TRSDOS Start-Up Dialog 



Whenever you reset the Model III Disk System, it loads trsdos and begins the 
start-up dialog. 

1 . The trsdos version number and date of creation will be displayed, followed 
by the amount of ram (32K or 48K) and the number of drives in the system. 

2. trsdos will prompt you to enter the date in the form mm/dd/yy. For example. 
07/04/80 for July 4, 1980. Type in the correct date and press (ENTER) , trsdos 
will not continue until you type in the date correctly. 

3. trsdos will prompt you to enter the time in 24-hour form hh:MM:SS. For 
example, 14:45:00 for 2:45 p.m. Type in the correct time and press [ENTER) . If 
you don't wish to set the time, simply press CENTER) at the beginning of the 
line, trsdos will set the time to 00:00:00. 

4. trsdos will now display the message, TRSDOS READY 

Whenever this is displayed, you are in the trsdos ready mode, and you may 
type in a trsdos command. 
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Important Disk Operations 

In this section we will describe three very important operations: 

1 . Duplicating the trsdos diskette (backup) 

2. Initializing a data diskette (format) 

3. Converting files from Model I to Model III trsdos (convert). 

All new customers should complete the trsdos backup procedure now; multi- 
drive customers should also complete the format operation for a few diskettes. 
Detailed information is provided later in this manual; here we will simply 
outline the procedures. 

Making a BACKUP (Duplicate) of TRSDOS 

Your first operation should be to duplicate the trsdos diskette you received 
from Radio Shack. The trsdos diskette contains a utility program called 
backup to accomplish this. 

1 . Locate the trsdos diskette and a new, blank diskette. The trsdos diskette 
will be referred to as the "source," while the blank one will be called the 
"destination," during backup. 

2. Start trsdos as explained in the previous section. TRSDOS READY should be 
displayed. 

3. Type: BACKUP (ENTER) 

4. trsdos will now load and start backup. It will ask you: 

SOURCE DRIVE NUMBER? 

Specify the drive which contains the original trsdos diskette by typing: 



CENTER) 

Next trsdos will ask: DESTINATION DRIVE NUMBER? 

Now specify the drive which will be used for making the duplicate trsdos. If 
you have two or more drives in your system, type: 1 CENTER) 

trsdos will ask: SOURCE DISK MASTER PASSWORD? 



Type: PASSWORD (ENTER) 

(password is the password of the supplied diskette.) 

Now'the duplication process will begin. 

If the destination diskette is not formatted, backup will format it before 
continuing. (Before any diskette can be used, it must be initialized or 
"formatted" — the data regions defined and labeled, and a table of contents 
or "directory' 1 created.) 
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If you are using a single-drive system, trsdos will prompt you to swap 
source and destination diskettes several times during the formatting/backup 
process. 

After a single-drive backup, trsdos will display the message: 



INSERT SYSTEM DISKETTE CENTER] 



Be sure you have a trsdos diskette in Drive 0, then press [ENTER) . 

The duplication process is now complete. We suggest you save the original 
trsdos and use the duplicate as your working copy. If anything happens to the 
working copy, you can make another one from the original. 



Making a Data Diskette (FORMAT) 

This section applies to multi-drive systems only. 

Drive must always contain a trsdos diskette, so the Computer can have 
access to the system programs stored there. Much of the storage capacity of this 
diskette is taken up by the system programs. 

However, the other drives in the system may contain tl data" diskettes which 
have no system programs. All of the storage capacity of such diskettes is 
available for your programs and data. 

The format utility program takes a diskette and initializes or "formats" it. 
If the diskette was previously formatted, all prior information can be lost. 
The resultant diskette contains no system files and may only be used in 
Drive 1, 2 or 3. 



1 . In the trsdos ready mode, type: FORMAT CENTER) 

2. trsdos will start the formatter program and ask you a series of questions: 



FORMAT WHICH DRIVE? 



Insert a blank diskette into Drive 1 . Type: i (ENTER) 

DISKETTE NAME? 

This name will serve as an internal label for the diskette. Type in any 
appropriate name of one to eight letters and numbers, starting with a letter. 
Press CENTER) at the end of the name. 

MASTER PASSWORD? 

The password may be from one to eight letters and numbers, starting with a 
letter. Press CENTER) at the end of the password. 

Use of the password allows backup, prot, and purge access to all non- 
system files. Unless special protection is needed, we suggest you use the 
password password. Whatever password you select, don't forget it! 
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If the diskette contains data, trsdos will warn you: 

DISKETTE CONTAINS DATA » USE DISK OR NOT? 

The warning is needed since format erases all previous information from the 
diskette. Type N CENTER) to cancel format; type Y CENTER] or U CENTER] to 
continue it. 

3. trsdos will now format and verify the diskette. The data diskette will then 
be ready for use in Drive 1 , 2, or 3. 

Model I/III Conversion (CONVERT) 

In general, Model I trsdos diskettes cannot be used in a Model III Disk 
System. However, Model III trsdos includes a special program, convert, to 
read a Model I trsdos diskette and copy its non-system files onto a Model III 
trsdos diskette. 

In two-drive systems, the files must be copied onto a Model III system diskette; 
in three- or four-drive systems, the files may be copied onto a data diskette. 

Here are abbreviated instructions for using this program. For further details, see 
convert. 

1 . Using a Model I Disk System, remove all passwords from the diskette to be 
converted. You can do this with the prot command, described in the Model I 
TRSDOSlDisk basic Owner's Manual. 

2. Start Model III trsdos. 

3. Place the Model I diskette in Drive I, 2 or 3. (In two-drive systems, use 
Drive 1; in three- or four-drive systems, Drive 2.) 

4. In three- or four-drive systems, place a Model III data diskette in Drive 1 . 



5. Type: CONCERT CENTER) 

4. The conversion program will start by asking for the source drive number. 
Type in the number of the drive containing the Model I diskette, then press 
CENTER] . 

5. Next, the conversion program will ask for the destination drive number. Type 
in the number of the drive containing the Model III diskette, then press 
(ENTER) . (In two-drive systems, use Drive 0; in three- or four-drive systems, 
Drive 1 .) 

6. Now all the non-system files will be converted and copied onto the 
destination diskette. As each file is copied, its name will be displayed. 

7. When the process is completed, you may remove the Model I diskette. It is 
unchanged by the convert program. The destination diskette contains the 
converted files. 

8. To restore password protection to the converted files, you may use the prot 
or attrib command. 
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Disk BASIC 

Quick Instructions for Using Disk BASIC 

In this section we'll "walk you" through the following procedures: 

1. Starting Disk basic 

2. Running a simple program 

3. Saving a program in a disk file 

4. Loading a program from a disk file 

For programming information, see the Disk basic section of this manual. 
Here we are showing procedures only. 




Starting Disk BASIC 



Under trsdos ready, type: BASIC (ENTER) 

The Computer will load and start basic. First, it will ask two questions. 
Press (ENTER) in response to each of them. 



HOW MANY FILES? CENTER) 



MEMORY SIZE? (ENTER) 

A heading will be displayed, followed by: 

READY 

You may now begin using Disk basic. 

Saving a Program 

You should have a program in memory, and be in Basic's ready mode. Type: 



SAVE "PROGRAM" (ENTER) 

basic should now save the program in a disk file we arbitrarily named 
"program." Any other suitable file name would do. 



Loading a Program 

For this sample session, we will load the program just saved. 

First type: NEN (ENTER) to erase it from memory. (This is to prove that it can be 
retrieved from the disk file.) 
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Now type: LOAD " PROGRAM" (ENTER) and basic will load the specified 
program. 

You may now list it and run it. 

For further information on using Disk basic, see Section 3 of this manual. 

Setting the Cassette Baud Rate under Disk 
BASIC 

trsdos sets the cassette baud rate to High, If you would like to change this, use 
the following trsdos command; 



PATCH BASIC/CMD < ADD = 5202 ,FIND = 02) ,CHG=FF ) CENTER) 
Consequently, you will be prompted with: CASS? whenever you start Disk 

BASIC. 

You may then type either H (High) or L (Low) to choose the rate you need. 

To change the system diskette back to its original state (i.e., no CASS?), simply 
use the trsdos patch command again but reverse the find and chg values. 
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Troubleshooting and Maintenance 

If you have problems operating your Model III Disk System, please check the 
following symptoms and cures, and check the corresponding table in your 
Model III Manual. 

If you can't solve the problem, take the unit to your local Radio Shack. We'll 
have it fixed and returned to you as soon as possible. 



Symptom 


Cure 


Disk drive motors run 
continuously when the Computer 
is turned on. 


Check external drive connection sequence. 
Drive 26-1 1 64 must always be the last 
external drive. 


Computer will not load trsdos. 


1 . Make sure you have inserted the 
trsdos diskette properly in Drive 0. 

2. Make sure ail peripherals are properly 
connected. 


Error Messages 


Look up the message in the trsdos or 
basic Error Message Section. The "cure" 
should be listed. 


Frequent disk i/o errors 


1 . Diskette is partially erased. Backup the 
diskette, then re-format it. 

2. Diskette is worn out. Use backup copy, if 
available, to make a new working copy. 

3. Disk drives need cleaning or alignment 
by Radio Shack service technicians. 



Maintenance 

For reliable operation, the disk drives must be kept clean and properly aligned. 
These procedures should be done by Radio Shack service technicians, according 
to the following schedule: 



Degree of Use 

Commercial data processing 
environment 

Occasional home use 



Maintenance Interval 

Every month for medium use. 

Every 8-10 months; more often if 
needed. 



For further instructions, see the Troubleshooting and Maintenance section in 
your Model III Manual. 
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Notation and Abbreviations 

For the sake of clarity and brevity, we've used some special notation and type 
styles in this book, 

capitals and punctuation 

indicate material which must be entered exactly as it appears. (The only 
punctuation symbols not entered are ellipses, explained below.) For example, 
in the line: 

DUMP LISTER (START = 70O0,END = 7100,TRA = 7004) 

every letter and character should be typed as indicated. 

lowercase italics 

represent words, letters, characters or values you supply from a set of acceptable 
values for a particular command. For example, the line: 

LIST filename 

indicates that you can supply any valid file specification after list. 



Ellipsis indicates that the preceding items can be repeated. For example: 

ATTRIB filename (option, . . .) 

indicates that several options may be repeated inside the parentheses. 

b 

This special symbol is used occasionally to indicate a blank-space character 

(ASCII code 32 decimal, 20 hexadecimal). 

PRINT "BHbltt!" 

X'nnnn 

Indicates that nnnn is a hexadecimal number. All other numbers in the text 

of this book are in decimal form, unless otherwise noted. 

X'7000' 

indicates the hexadecimal value 7000 (decimal 28672). 

COMPUTER TYPE 

Any words, letters, or numbers that are displayed on the screen will be in 
computer type (dot-matrix). Uppercase letters are used; however, your screen at 
times may display lowercase letters instead. 
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Specifications 



Diskettes 



Diskette Organization 
(Formatted Diskette) 



Operating Temperature 

Power Requirements 
(External Drives) 



5 [ A" mini-diskettes 
Radio Shack Catalog 
Number 26-305, 
26-405 (package of three), 
or 26-406 (package of 10) 

Single-sided 

Double-density 

40 Tracks 

18 Sectors/Track 

256 Bytes/Sector 

55 to 80 Degrees Fahrenheit 
13 to 27 Degrees Celsius 

120 VAC, 60 Hz, 28 VA (240 VAC, 50 
Hz, Australian; 220 VAC, 50 Hz, 
European) 
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Description of TRSDOS 

What Is TRSDOS? 

trsdos (pronounced "triss-doss") stands for "trs-80 Disk Operating System." 
It fulfills three roles: 

1 . Master Program 

2. Command Interpreter 

3. Program Manager 

As the master program, trsdos enables the microprocessor and its various 
components to interact efficiently. The components include: 

• Random Access Memory (ram), trsdos reserves space for its own needs and 
allocates space for user programs. 

• Disk Drives, trsdos interfaces with the disk hardware and provides a file 
system for storing system and user data on diskettes. 

• Input/output devices. These include the keyboard, video display, printer, and 
rs-232 c equipment. 

trsdos is also a command interpreter. Whenever it displays TRSDOS READY, 
you may enter commands that control how the system works. These are known 
as ' 'library 1 ' commands. 

In its role as program manager, trsdos will load and run system or user 
programs. During this time, the system or user program is in control of the 
Computer. 

Figure 7 illustrates the relationships between these three roles. 

Where Does BASIC Fit In? 

Referring to Figure 7, you'll see that Disk basic falls under the "language 
package" category. 

Disk basic consists of some general enhancements to Model III basic, plus the 
disk input/output capability. It uses Model III basic (stored in rom) whenever 
possible. For instance, the Model III basic rom includes all of the mathematical 
functions. 

If you're used to the non-disk system, there's one difference you should 
understand from the beginning: In the non-disk system, basic is in control when 
you start-up. In the disk system, however, trsdos is in control when you start- 
up. You have to tell trsdos to load and run basic. Only then can you begin 
running a program written in basic. 
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How TRSDOS Uses RAM 

trsdos is stored on the system diskette included with your Disk System Each 
time the Computer is turned on or reset, the trsdos master program is loaded 
into ram so it can take charge. 

trsdos occupies approximately 40,000 bytes of space on the diskette; however 
only a portion of that is in ram at once. This is possible because trsdos is ' 
divided into several independent "modules." 

The "resident" module is in memory at all times. It consists of input/output 
drivers, tables, the command interpreter, and other essential routines. 

Additional modules are loaded as needed, and replaced (or "overlaid") bv other 
modules when they are no longer needed. 

Note: After you enter a library or utility command, you will usually hear 
trsdos accessing the system disk. It is loading an overlay module which 
contains the code necessary to complete the command. 

The Memory Map in Figure 8 illustrates how trsdos utilizes the available 
memory space. 
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Using TRSDOS 

Entering a Command 

Whenever the trsdos prompt, 

TRSDOS READY 

is displayed, you can type in a command, which can be no more than 63 
characters in length. You must press CENTER) to end the line, trsdos will then 
"accept'' the command. 

For example, type: CLS (MM) trsdos will clear the Display and the trsdos 
ready prompt will reappear. 

In general, your commands will require more than one word. For example, to 
kill (delete) a file named myname, you have to specify the command and the 
filename. 

KILL MYNAME CENTER] 

tells trsdos to find the file named myname, eliminate it from the diskette, and 
release the space previously occupied by that file. 

Whenever you type in a line, trsdos follows this procedure: 

1 . First it checks to see if what you've typed is the name of a trsdos command. 
If it is, trsdos executes it immediately. 

2. If what you typed is not a trsdos command, then trsdos will check to see if 
it's the name of a program file on one of the drives. 

3. When searching for a file, trsdos looks first through Drive 0, then Drive 1 , 
etc., unless you include an particular drive specification with the file name' 
— or specify the master command (see Library Commands). 

If trsdos finds a specified user file, it will load and execute the file if it is a 
program file. Otherwise, you'll get an error message. 

Command Syntax 

Command syntax is a command's general form (like the grammar or structure of 
an English sentence). The syntax tells how to use keywords (such as dir, list, 
create, etc.) together with the necessary parameters and punctuation. 

If you need help remembering the syntax form of a specific command while 
you're operating trsdos, type in: 

HELP command CENTER] 



-^, 
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command should be the specific Library Command you're having trouble with. 
trsdos will give you the syntax format as well as a brief definition of the 
command. 




Commands (Syntax Forms) 

No-file commands 






tviW'a^"iiiwiL|t' ■ . ,. ' '["■"..'■' '■■'^■'7"''"''""'\"""['"''::^^ 



wmimMUm^ purpose of the 

inptit files (see build anil do). 






One-file commands 
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Two-file commands 



command filename delimiter filename (options) comment 
filename is a stpdard tbsdds file specification. 
delimiter is a blank space , 
options— See definition above. 
comment— See definition above. 



File Specification 

The only way to store information on a diskette is to put it in a disk file. 
Afterwards, that information can be retrieved via the file name you gave the file 
when you created or renamed it. 

A file specification has the general form: 



filen^me/extpB$sword:d 

filename consists of a letter^ 
or numbers. 

fextis an optional name-extensipn; 4 ext' is a sequence of up to three 
letters or numbers, starting with a letter. 

password^ an optional password; 'password' is a sequence of up to 
eight letters or numbers, starting with a letter. 

:d is an optional disk-drive specification; 4 d' is one of the digits 



Note: There can be no blank spaces inside a file specification, trsdos 
terminates the file specification at the first blank space. 

For example: FILEA/TXT*MANAGER:3 references the file named filea/txt 
with the password manager, on Drive 3. 
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The name, extension, and drive-specification all contribute to the uniqueness of 
a file specification. The password does not. It simply controls access to the file. 

File Names 

A file name consists of a name and an optional name extension. For the name, 
you can choose any letter, followed by up to seven additional numbers or letters. 
To use a name extension, start with a diagonal slash / and add no more than 
three numbers or letters; however, the first character must be a letter. 



For example: 



MODEL3/TXT 
NAMES/ A 12 
TEST 



INVENTORY 
AUGUST/A 15 
TEST1 



DATA11/BAS 
WAREHOUS 
TEST 1 /A 



are all valid and distinct file names. 



Although name extensions are optional, they are useful for identifying what type 
of data is in the file. For example, you might want to use the following set of 
extensions: 



/BAS 
/TXT 
/CMD 
/DAT 



for basic program 

for ascii text 

for machine-language command file 

for data 



One advantage of using extensions is that you can tell by just looking at the 
directory what kind of information a file contains. 

Another advantage is that trsdos can recognize certain extensions. For 
example, if a file has the extension /cmd, the trsdos will load and attempt to 
execute that file when you type: filename (ENTER) omitting the extension /cmd. 



Drive Specification 



If you give trsdos a command such as: KILL TEST/A trsdos will search for 
the file test/a first in Drive 0, then in Drive 1 , 2, and finally in Drive 3 until it 
finds the file. 

Anytime you omit a drive-specification, trsdos will follow this sequence, 
unLess you use the master command. 

It is possible to tell trsdos exactly which drive you want to use by specifying 
the drive. A drive specification consists of a colon followed by one of the digits 
0, 1 ,2, or 3, corresponding to one of the four drives you might be using. 

For example: KILL TEST/A : 3 tells trsdos delete the file test/a on Drive 3 
only. 
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Anytime trsdos has to open a file (e.g., to list it for you), it will follow the 
same sequence. When trsdos has to write a file, it will skip over any write- 
protected diskettes. 

Password 

You can protect a file from unauthorized access and use by assigning passwords 
to the file. That way, a person cannot gain access to a file without using the 
appropriate password. 

It's important to realize that every file has a password, even if you didn't specify 
it when the file was created. In such instances, the password becomes eight 
blank spaces. In this case, the file becomes unprotected — anyone can gain total 
access simply by referring to the filename. 

trsdos allows you to assign two passwords to a file: 

• An "Update word," which grants total access to the information 

• An "Access word," which grants limited access to the information (see 
attrib) 

When you create a file, the Update and Access words are both set equal to the 
password you specify. You can change them later with the attrib command. 

A password consists of a period followed by one to eight letters or numbers. If 
you do not assign a password to a file, trsdos uses a default password of eight 
blanks. 

For example, suppose you have a file named secret/bas. and the file has 
myname as an update and access word. Then the command: KILL SECRETS/ 
BAS will not cause the file to be killed. You must include the password myname 
in the file specification. 

Suppose a file is named domain/bas and has blanks for the password. Then the 
command: KILL DOMAIN/BAS*GUESS will not be obeyed, since guess is not 
the password. 

A Few Important Definitions 

System vs. Data Diskettes 

A system diskette is one which contains the trsdos disk operating system 
software. Subject to space limitations, it may also contain your own files. A 
system diskette must always be in Drive while the Computer is in use. 

A data diskette, on the other hand, does not contain the operating system 
software, and therefore cannot be used in Drive 0. It may be used in Drive 1 , 2 
or 3. Such a diskette has a maximum of space available for storing your own 
programs and data. 
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System, Program, and Data Files 

System files include the trsdos operating system software, the basic language 
interpreter, the format, backup and convert utilities, and other software 
which is released by Radio Shack. These files appear in the Directory with an 
"S" attribute. (See dir) 

Program files are stored in a special format which allows them to be loaded and 
executed directly from the trsdos ready level. For example, the basic 
interpreter is a program file. 

Data files include all files that are not in the correct format to allow loading and 
executing from trsdos ready. For example, a program written in basic will be 
stored as a data file. It can be loaded and executed from basic, but not from 

TRSDOS READY. 

Master Passwords 

Each diskette is initially assigned a master password during format or backup. 
(Your master password for trsdos is password.) The master password allows 
you to use backup, purge, and prot on a diskette. Using a diskette's master 
password, you may change it (see prot). 
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TRSDOS Library Commands 



APPEND 
Append files 



append source-file destination-file 

soume-ttle is the specification for the file which is to be 
copied onto the end of the other file. 

destination-fileis the specification for the file which is to 
--wofw'4be^8iidagfr(8df|Won). 

Note: Both source- and destination-files must be in ascii 
format (date files or basic proflrams saved with the a 
option). 



append copies the contents of the source-file onto the end of the destination-file. 
The source-file is unaffected, while the destination-file is extended to include the 

source-file. 

Note: The logical record lengths must match. See dir for more information on 
logical record lengths. 

Examples 

APPEND WORDFILE/C WORDFILE/D 

A copy of wordfile/c is appended to wordfile/d. 

APPEND REGIONi/DAT TOTAL/DAT ♦ GUESS 

A copy of regioni/dat is appended to total/dat, which is protected with the 
password guess. 

Sample Uses 

Suppose you have two data files, payroll/a and payroll/b. 
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PAYROLL/ A PAYROLL/B 



AtKinst W*R Lewis* G*E ♦ ♦ 

BaKer t J.B Miller * L*Cu .♦♦♦♦♦♦ 

Chambers, C*P Peterson* B 

Dodson* M,W Rodrisfuez* F* ♦♦♦♦♦. 

KicKawon * T ♦ Y ♦ ♦ ♦ ♦ ♦ ♦ 

You can combine the two files with the command: 

APPEND PAYROLL/B PAYROLL/A 
payroll/a will now look like this: 

PAYROLL/A 

Atkins* W ♦ R ♦ ♦ ♦ 

Baker* J+B* ♦♦♦♦♦♦♦♦ 

Cham be rs * C ♦ P 

Dodson* M ♦ W ♦ ♦ 

Kick am on * T ♦ Y 

Lewis* G ♦ E ♦ ♦ ♦ ♦ 

Miller* L ♦ ♦ ♦.♦♦♦♦♦ 
Peterson* B ♦ +♦♦♦♦♦♦ 
Rodriguez* F * ♦♦♦.♦. 

payroll/b will be unaffected. To see the APPENDed file, type LIST PAYROLL /A 
(ASCII). 



Note: Do not load a program under basic after an append. 

ATTRIB 

Change a File's Password 



attrib file (visibility,^ = name,upo = na/ne,PR0T = 

'" r' '■";■- ."'.''.S-;'.-^; '■ \':|^i^jg^k^itfji4ki]v.:'lf . "A : cfc--== , , -l» -'used , the acco»st^*irot^\; : i^: : »pftd^ : . : :;-;;/;-'- ^■:- v";:a'. " : : ; 



upd = name tells trsdos the update word. If omitted, the update word 
is unchanged. If upd= , Is used, the update word is Set to> 
blanks. 
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■i^*U^M^^^-;t^'fmiimh level for access, tf omitted 
Level Degree of access granted by access word 



FULL 
KILL 

NAME 
WRITE 
READ 
EXEC 



Full access, no protection. 

Kill, rename, read, execute, and write (gives 

total access, i.e., the least-protected). 

Rename, read, execute, and write. 

Read, execute, and write. 

Read and execute. 

Execute only. 



Note: Each level allows access to itself plus all lower levels. 



attrib lets you change the passwords to an existing file or makes the file 
invisible or non-invisible. Passwords are initially assigned when the file is 
created. At that time, the update and access words are set to the same value 
(either the password you specified or a blank password). 

Examples 

ATTRIB DATAFILE ( I ,ACO JULY14 »UPD = M0USE , PR0T = READ ) 

Makes the file invisible, sets the access password to julyh and the update 
password to mouse. Use of the access word will allow only reading and 
executing the file. 

ATTRIB PAYROLL/BAS, SECRET (N»ACC=») 

Sets the access word to blanks. The file is made non-invisible and the protection 
level assigned to the update word is left unchanged. 

ATTRIB OLD/DAT. APPLES <UPD=») 
Sets the update word to blanks. 

ATTRIB PAYROLL/BAS, PW (PR0T=EXEC) 

Leaves the access and update words unchanged, but changes the level of access. 

Sample Uses 

Suppose you have a data file, payroll, and you want an employee to use the 
hie in preparing paychecks. You want the employee to be able to read the file 
but not to change it. Then use a command like: 



28 



TRSDOSL^d 



ATTRIB PAYROLL (I *ACC = PAYDAY t(JPD = AV0CAD0 tPROT = READ) 

Now tell the clerk to use the password payday (which allows read only); while 
only you know the password, avocado, which grants total access to the file. 

Protecting BASIC Programs 

You may give a basic program execute-only protection using the attrib 
command. For example, suppose the program is named test (no password). 
Under trsdos ready, execute this command; 

ATTRIB TEST < ACC= »UPD = VALLEY ,PR0T = EXEC ) 

Now test has a blank access password, an update password of valley, and an 
access level of execute only. Without using the update password, there is now 
only one way to execute the program: 

1. Start basic. 

2. Type: RUN "TEST" 

(This is the only way to access the program. If the operator attempts to load 
it instead, basic will erase the program from memory before returning with 
ready.) 

After the run "test" command, basic will load and execute the program. If 
the operator presses (BREAK) or if the program ends normally, basic will erase the 
program before returning with the ready message. This makes it impossible to 
obtain a listing of the program — unless the update password is used. 

Of course, if you use the update password, you may gain full access to the 
program. 



AUTO 

Automatic Command after System Start-up 



command-line gives trsdos a command 01 name of an executable 
program file created by build. 

\i command-line \$ given, the command will be executed on reset/ 
power-up. 

if mmmand-lme is omitted, the previous auto command is erased 
from the diskette. 
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This command lets you provide a command to be executed whenever trsdos is 
started (power-up or reset). You can use it to get a desired program running 
without any operator action required, except for typing in the date and time. 

When you enter an auto command, trsdos writes command-line into its start- 
up procedure, trsdos does not check for valid commands; if the command line 
contains an error, it will be detected the next time the System is started up. 

Examples 

AUTO DIR (SYS) 

Tells trsdos to execute the command dir (sys) after the start-up procedure. 
Each time the System is reset or powered up, it will automatically execute that 
command after you enter the date and time. 

AUTO BASIC 

Tells trsdos to load and execute basic each time the System is started up. 

AUTO FORMS ( WIDTH=S0) 

Tells trsdos to reset the printer width parameter each time the System is started 
up. 

AUTO PAYROLL/CMD 

Tells trsdos to load and execute payroll/cmd (must be a machine-language 
program) after each System start-up. 

AUTO DO STARTER 

Tells trsdos to take automatic key-ins from the file named starter after each 
System start-up. See build and do. 

To Erase an AUTO Command 

Type: AUTO [ENTER] 

This tells trsdos to erase any automatic command. The command will be 
deleted the next time you power-up or reset the System. 

The acknowledgement: AUTO = "" is displayed after an erasure. 

To Override an AUTO Command 

You can bypass any automatic command by holding down (ENTER] while pressing 
reset. You must continue holding down CENTER) until you are prompted for the 
date during the initialization process. 
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Create an Automatic Command Input File 




file is a file specification which cannot include an extension, 



This command lets you create an automatic command input file which can be 
executed via the do command. The file must contain data that would normally 
be typed in from the keyboard to the trsdos ready mode. 

build files are intended for passing command lines to trsdos just as if they'd 
been typed in at the trsdos ready level. Note: clear cannot be used in a do 
file. 

When you enter the build command, build creates the file and immediately 
prompts you to begin inserting lines. Each time you complete a line, press 
(ENTER) . (While typing in a line, you can use the usual cursor control keys for 
erasures and corrections.) 

To end the build file, simply press (BREAK) at the beginning of a line. 

First type: BUILD filename 

You will then be prompted to type in the command text. You then type in up to 
63 characters, then press (ENTER) . You may enter as many lines as necessary. 
Press (BREAK) to quit and return to trsdos ready. 

A Sample BUILD-File 

Here's a hypothetical BUiLD-file that initializes the serial interface and the printer 
driver: 

SETCOM <BAUD=12(Z}0,WAIT) 

FORMS <WIDTH=80) 

PAUSE SERIAL INTERFACE & PRINTER INITIALIZED 
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CLEAR 

Clear User Memory 



\^i^fMmim^^^M^ start clearing user memory, aaaa 
is a fdur-drgit hexadecimal number from 6000 to the end of user 
memory. If this option Is omitted, eooo is used. If this option Is 
used, end == bbbb must also he used. 

end = bbbb tells trsdos to clear user memory to a specified end. bbbb 
* s a feuMigif hexadecimal number no less than the start 
number ano' no gfeater than the top of memory. If this option is 
used, start = aaaa must also be used. 

mem = ccce sets the memory protect address, cccc is a four-digit 
hexadecimal number from 0000 to ffff. If this option is omitted, 
the memory protect address is reset to end of user ram. 

If all options are omitted, all available ram is cleared, memory- 
protect is reset to end of memory, the Display is cleared, all 1/0 
drivers are reset (see Memory Requirements of trsdos). 



This command gets you off to a fresh start. 

Depending on the options you select, this command will: 

• Zero user memory (load binary zero into each memory address above 6000) 

• Clear the Display 

• Un-protect all memory 

See Memory Requirements of trsdos for more information on the memory- 
protect address. Note: clear cannot be used in a do file. 

Example 

CLEAR (START=9000,END=0A000) 

Note: Hexadecimal numbers which begin with a letter must be prefaced by zero 
(see above example). 

CLEAR (MEM=7000) 
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CLOCK 

Turn On Clock Display 






This command controls the real-time clock display in the upper right corner of 
the Video Display. When it is on, the 24-hour time will be displayed and 
updated once each second, regardless of what program is executing. 

Clock display is off at trsdos start-up. 

Note: Except during cassette and disk i/o, the real-time clock is always running, 
regardless of whether the clock display is on. 

Examples 

CLOCK 

Turns on the clock display. 

CLOCK (OFF) 

Turns the clock display off. 

See time and date. 




CLS 

Clear the Screen 



This command clears the Display and puts it in the 64 character/line mode. 

Example 

CLS 
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COPY 

Copy a File or Files 



source-file is a file specification for the file to be copied. 
destination-file is a file specification for the name and drive of the 

itt letis Trsdos to copy the file onto drive d, using the same file name, 

/exits a "wiWicard" file specification in which the file name is 
omitted and the extension is given, trsdos will copy all files 
which have a matching extension, regardless of the file name. 

:tf is defined above. 



This command copies source-file into the new file defined by destination-file. 
This allows you to copy a file from one disk to another, using a single drive if 
necessary. (In the latter case, you must include drive specifications in both file 
specifications.) For single-drive systems (Drive 0), both diskettes must contain 
trsdos. (i.e., Data diskettes aren't allowed in Drive 0.) 

Examples 

COPY OLDFILE/BAS NEWFILE/BAS 

Copies oldfile/bas into a new file named newfile/bas. trsdos will search 
through all drives for oldfile/bas, and will copy it onto the first disk which is 
not write-protected. 

COPY NAMEFILE/TXT :1 

This command specifies a file named namefile/txt to another disk. 

COPY FILE/EXT:0 :i 

This command copies file/ext from Drive to Drive 1 . 
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COPY /BASsO 5i 

tells trsdos to copy all Drive files which have the extension /bas. The files 
will be copied onto Drive 1 , using their present file names and extensions. 

Sample Use 

Whenever a file is updated, use copy to make a backup file on another disk. You 
can also use copy to restructure a file for faster access. Be sure the destination 
disk is already less segmented than the source disk; otherwise the new file could 
be more segmented than the old one. (See free for information on file 
segmentation.) 

To rename a file on the same disk, use rename, not copy. 



CREATE 

Create a Pre-allocated File 



te^ If omitted, tm is as^iini#. f ; 

refc&rdstlosired; it omitted, no records are al|o0pC : 



This command lets you create a file and pre-allocate (set aside) space for its 
future contents. This is different from the default (normal) trsdos procedure in 
which space is allocated to a file dynamically, i.e., as necessary when data is 
written into the file. 

If you open the file for sequential writes, trsdos will de-allocate (recover) any 
unused granules when the file is closed. If you open the file for random access, 
trsdos will not de-allocate space when the file is closed. 
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You may want to use create to prepare a file which will contain a known 
amount of data. This will usually speed up file write operations. File reading 
will also be faster, since pre-allocated files are less segmented or dispersed on 
the disk — requiring less motion of the read/write mechanism to locate the 
records. 

Examples 

CREATE DATAFILE/BAS <REC=300, LRL=0) 

Creates a file named datafile/bas, and allocates space for 300 256-byte 
records. 

CREATE NAMES/TXT. IRIS ( LRL=64 iREC = 50 ) 

Creates a file named names/txt protected by the password iris. The file will be 
large enough to contain 50 records, each -64 bytes long, 

CREATE PAYROLL/BAG 

Creates a file named payroll/bas but allocates no space to it. 

Sample Use 

Suppose you are going to store personnel information on no more than 250 
employees, and each data record will look like this: 

Name (Up to 25 letters) 

Social Security Number (11 characters) 

Job Description (Up to 92 characters) 

Then your records would need to be 25 + 1 1 + 92 - 128 bytes long. 

You could create an appropriate file with this command: 

CREATE PERSONNL/TXT ( REC = 250 ,LRL= 128 ) 

Once created, this pre-allocated file would allow faster writing than would a 
dynamically allocated file, since trsdos would not have to stop writing 
periodically to allocate more space (unless you exceed the pre-allocated 
amount). 



DATE 

Reset or Get Today's Date 



mm/dd/yyi$ the specification for the month (mm), day (*M) and 
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Easts must be a two-digit decimal number between the following 
ranges: 

mm 01-12 
dd 00-31 
W 00-99 

The specifleations are an option; however, if one specification is 
used, they all must be used. 

ftmm/dd/yym omitted, trsdos displays the current date. 

If mm/dd/yy Is given, trsdos resets the date. 



This command lets you reset the date or display the date. 

You initially set the date when trsdos is started up. After that, trsdos updates 
the date automatically, using its built-in calendar. You can enter any two-digit 
year after 1900. 

When you request the date, trsdos displays it in the format: (37/25/80 for July 
25, 1980. 

Examples 

DATE 

Displays the current date. 

DATE 07/18/80 

Resets the date to July 18, 1980. 




DEBUG 

Start Debug Monitor 



DEBUG 



This command starts the debug monitor, which allows you to enter, test, and 
debug machine-language programs. 
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Its features include: 

• Full- or half-screen displays of memory contents 

• Commands for modifications to ram and register contents 

• Single-step execution of programs 

• Breakpoint interruption of program execution 

• Transfer of control (Jump) 

• "Editing" of disk-files 

debug uses the memory area from xmeoo' to x*54FF (see trsdos Memory 
Map), debug can only be used on programs in the user area x^w to top. 

Examples 

DEBUG 

Turns debug on. Press ® to quit debugging and return to trsdos. 



Turns debug off. 

Command Description 

Debug commands are usually entered by pressing a single key. In most cases, 
you do not have to press (INTER) after the command has been typed in. Either' 
a prompt will immediately be displayed or debug will execute the operation 
without further instruction. 

In some cases, you will have to enter a specific hexadecimal value or address 
(see r and j commands, for instance). Instead of pressing (ENTER) after the 
address is typed in, you will have to press (SPACEBAR) . 

Once you have entered the debug program, you may use any of the following 
special commands: 

D (Display Memory Contents) 

Press ® to display the contents of memory, trsdos will respond with the 
prompt: D ADDRESS - You should type in the hexadecimal address of the 
memory location you wish to see. 

The display will be either half- or full-screen, depending on the format you are 
currently using (see below). 
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X (Half-Screen Display) 

Press ® to put the Display in the half-screen format. A 128-byte block of 
memory will be displayed starting with the next lowest address which is a factor 
of 16. 

Figure 9 shows a typical half-screen format. 

S (Full-Screen Display) 

Press ® to display the contents of a 256-byte block of memory starting with the 
next lowest address which is a factor of 256. 

Note: The last 16 bytes on the Display will be overlaid by any command line 
typed in after the full-screen display is updated. 

M (Modify RAM) 

Press ffi) to change to the disk utility display format (see the f command). 
trsdos will respond with the prompt: M ADDRESS - You should type in the 
four-digit hexadecimal address of the memory location you wish to modify, 
followed by a blank space (anything other than a space will abort the 
command). 

The display will change to the memory edit format. The cursor will appear as a 
blinking character at the specified location. 

To exit the modify mode, press CENTER) to keep all changes made. 

R (Change Register Contents) 

Type: 




feadfticj zeros are assumed. 



I (Instruction Single-Step) 

Pressing CD will allow the Computer to execute a single z 80 instruction. The 
display will then be updated. 
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Start address 
of one 16-byte 
"row" of RAM 



RAM display — 

A hex contents 

of each byte 



2-80 register contents ' 
Op-code Instructions at the "PC" address 



Figure 9. Half-Screen Format. 



The instruction in the memory contents referenced by the program counter is 
executed. The program counter is increased by the appropriate value, and the 
control is returned to debug. 

debug will not, however, step through a call or jump into a rom address. 

C (Call Single-Step) 

If you wish to complete an entire call/return sequence, press ©. The call is 
then executed and control is returned to debug when the subroutine returns. 
Otherwise, this instruction acts just like the I command. 

You will not be able to step through a call or jump into a rom address. 



ASCII display 

(• indicates a 

nondisplayable 

character) 




U (Update) 

Pressing © causes the Display to be updated repeatedly. Press any key to 
from this mode. 



exit 
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; (Increment Display Address) 

If the Display is half-screen, the first location shown is incremented by 16 when 
you press CD- If the full-screen format is displayed, the starting address will be 
incremented by 256. 

— (Decrement Display Address) 

If the Display is half-screen, the first location is decremented by 16 when you 

press Q- If the full-screen format is displayed, the starting address will be 
decremented by 256. 

J (Jump) 

Press GD to transfer control to a machine-language program, setting optional 
breakpoints. 

Debug will respond with the prompt: J ADDRESS? = 

You may type in a jump address and a breakpoint address. The command is 
terminated when you press (ENTER] . Type in the addresses in one of three 
formats: 




i«8BE$s? as aaaa.bbbb (1HTER) 

ial address specifying the jump 
destination. If omitted, the address in the pc register is used. 

mal address specifying a breakpoint. 
Before the Computer executes an instruction at this address, it 
will return control to debug, if this address is omitted, control 
will not return to debug. 



Notes: Breakpoints must be set at the beginning of z-80 instructions. You may 
not set breakpoints in rom addresses. The breakpointed address will contain an 
x*F7' until the breakpoint is encountered. Then the original contents will be 
restored and debug will take control again. 

Q (Quit) 

Pressing (J£) turns off debug and returns control to trsdos. 
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F (File Patch Utility) 

This command lets you load and modify the contents of a diskette file. 

When you press ©, debug will respond with the prompt: FILES PEC?. Enter the 
name of the file to be patched. 

debug will set up a full-screen display showing the first 256 bytes in the file. 
You can "page" through the file using the CD and Q keys. 

Figure 10 gives a typical display. 

In this file-display mode, both hexadecimal and ascii are given for each byte. If 
a code has no displayable character, a period is shown in the ascii area. 

The display control commands are like those for the normal file-display mode: 

CD Next page 

O Previous page 

To change the file contents, press ®. This puts you in a modify-memory mode 
like the one previously described. Use the arrow keys to position the cursor (a 
blinking character), then type in the correct contents as a hexadecimal value. 
When you are through changing a page on the display, press (ENTER) . The 
diskette file will be updated and you will be returned to the file-display mode. 

To cancel changes made, do not press (ENTER) , press (BREAK) . This will put you 
back in the file-display mode without updating the diskette file. You may press 
CD then Q to restore the page display to its actual contents. 

To quit patching a file, press (BREAK) while in the file display mode, debug will 
prompt you for a new file specification. Press (BREAK) again and you will be 
returned to trsdos ready. 



42 




Figure 10. Full-Screen Format 
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DIR 

List the Diskette Directory 



Dia;rffffiIV,SYS,PRT) 

:it k the desired drive directory, if omitted, Drive is assumed. 

m lists the invisible user files, if omitted, non-invisible user flies are 
listed. 

sys lists system and user files. If omitted, only non-invisible user files are 
listed. 

put lists the directory to the Printer. If omitted, the directory will be listed 
on the Video Display only. 

If no option is given, tbsdos lists non-invisible user files in Drive 0. 



This command gives you information about a disk and the files it contains. 

To pause the listing, press CD. To continue, press CENTER) . To terminate the 
listing, press (BREAK) . 

Examples 

DIR 

Displays the directory of non-invisible user files in Drive 0. 

DIR :l (PRT) 

Lists the directory of the user files in Drive 1 to the Printer. 



Sample Directory Listing 

(See Figure 11.) 

Definition of column headings 



© File Name — The name and extension assigned to a file when it was created 
The password (if any) is not shown. 

@ Attributes — A four-character field. 

The first character is either i (Invisible) or n (Non-invisible). 

The second character is s (System) or * (User) file. 

The third character gives the password protection status: 
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Figure 11. Directory Listing. 

x The file is unprotected (no password). 

a The file has an access word but no update word, 

u The file has an update word but no access word. 

b The file has both update and access words. 

The fourth character specifies the level of access assigned to the access word: 

Total access 

1 Kill file and everything listed below. 

2 Rename file and everything listed below. 

3 This designation is not used. 

4 Write and everything listed below. 

5 Read and everything listed below. 

6 Execute only. 

7 No access. 

® Number of Free Granules — How many free granules remain on the diskette. 

® Logical Record Length — Assigned when the file was created. 

© Number of Records — How many logical records have been written. 

© Number of Granules — How many granules have been used in that 
particular file. 
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® Number of Extents — How many segments (contiguous blocks of up to 32 
granules) of disk space are allocated to the file. 

© End of File (eof) — Shows the last byte number of the file. 

© Creation Date — When the file was created. 

DO 

Begin Auto Command Input from a BUILD-File 



do command-line 



command-line is the name of file created with build. No extension should 
be specified. The file will automatically be given the extension /bld. 



This command reads and executes the lines stored in a special-format file 
created with the build command. The System executes the commands just as if 
they had been typed in from the Keyboard. 

Command lines in a build file may include library commands or file 
specifications for user programs. 

When do reaches the end of the automatic command input file, it returns control 

tO TRSDOS. 

The debug and clear command cannot be included in a build file. 

In addition to executing trsdos library commands, you can load and execute 
user programs from a Do-file. You will probably want to make your program 
name be the last line in the Do-file. 

Examples 

DO STARTER 

trsdos will begin automatic command input from starter, after the operator 
answers the Date and Time prompts. 

AUTO DO STARTER 

Whenever you start trsdos, it will begin automatic command input 
from starter. 
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Sample Uses 

Suppose you want to set up the following trsdos functions automatically 
on start-up: 

FORMS (WIDTH=80) 
CLOCK (ON) 

Then use build to create such a file. If you called it begin, then use the 
command; AUTO DO BEGIN to perform the commands each time trsdos 
starts up. 



DUAL 

Duplicate Output to Video and Printer 




TRSDOS 



dual (switch) 



'm^'h9MM^0^mf on or off. If omitted, trsdos uses on. 



This command duplicates all video output to the Printer, and vice versa. It takes 
effect immediately. 

Notes: 

1 . Video and printer output may be different because of intrinsic differences 
between output devices and output software. 

2. Using the dual command will slow down the video output process. 

3. The dual command cannot be used during route and vice versa. 

4. The printer should be ready when you execute the command. 

Sample Use 



For a printed copy of all system/operator dialog, type: DUAL (ENTER) 



To turn off the dual process, type: DUAL ( OFF ) (ENTER) 
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DUMP 

Store a Program Into a Disk File 



w m file (start = aaaa, end = bbbb, tra = cccc, relo = dddd) 
file is the file specification 

start = aaaa is the start address of memory block, aaaa mm be a four- 
digit hexadecimal number greater than or equal to rvm: 

end = bbbb is the end address of the memory block, bbbb must be a four- 
digit hexadecimal number. 

tra^ eczcls the transfer address where execution starts wheh the program 
is loaded, ccce must be a four-digit hexadecimal number. If this 
option is omitted, the command will default to trsdos re-entry. 

reio - dd0 is the start address for relocating or loading the program back 
into memory, dddd must be a four-digit hexadecimal number. If this 
option is omitted, no relocation will take place. 

Note: Addresses must be hexadecimal form, without the x notation. 
You must add the prefix "0" to any hex number which begins with a 
letter, 



This command copies a machine-language program from memory into a 
program file. You can then load and execute the program at any time by entering 
the file name in the trsdos ready mode. 

Examples 

DUMP LISTER < START = 7000 ,END = 7100 ,TRA = 7004) 

Creates a program file named lister/cmd containing the program in memory 
locations x'70ocr to x'7ioo\ When loaded, lister/cmd will occupy the same 
addresses, and trsdos will protect memory beginning at x'70oo\ The program is 
executable for the trsdos ready mode. 

DUMP PR0G2 <START=7000,END=7F00»TRA=8010,RELO=8000) 

Creates a program file named proc,2/cmd containing the program in addresses 
x-7000' to x'7F00\ When loaded, prog2/cmd will reside from x'sooo' to X'hfoo\ 
Execution will start at x'soirr. 
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ERROR 

Display Error Message 



mnm number 

number is a decimal number for a trsdos error cade; 



This command displays a descriptive error message. For example, after 
receiving the message, * * ERROR 47 * * you may respond with the 
command: ERROR 47 [ENTER) and trsdos will display the full error message. 

For a complete list of error codes and messages, see the Technical Information 

section of this manual. 



FORMS 

Set Printer Parameters 



FORMS (WIDTH = W, HUES = /) 

width = wis the maximum number of characters per output line. If a line 
reaches this length, trsdos will insert a cartage Tetwrn to imm a new 
line. If this option is omitted, the current maximum width will be 
used. To disable the maximum line width feature, use width = 255. 
trsdos will not force new lines. 

tiNis = lis ths number of lines per page, trsdos does not use this value. 
However, basic will use it in computing the necessary page 
displacement for execution or if lprint chr$(12) is executed. If lines = / 
is omitted, the current value is used. 



This command lets you modify the printer forms control features of trsdos. 
The default values are: 

Maximum line width: 132 
Lines/page: 60 
forms also sets the line count to 0. 
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Examples 

If you are using 8'/ 2 "-wide forms, you will probably want to set width = 80- 

FORMS <WIDTH=80) 

If you are using 14"-long forms, you may want to set lines -78. 

FORMS (LINES=78) 

This change will allow the basic statement, lprintchr$(12), to advance a naze 
by the correct number of lines. 

Notes: 

1. The width you specify is stored in ram location 16427. The lines you 
specify is stored in ram location 16424. 

2. The Printer must be ready when you execute this command. 



FREE 

Display Disk Allocation Map 



(iwi tells trsdos to send the map to the Printer. 

It omitted; trsdos sends the map to the Video Display only. 



This command gives you a map of granule allocation on a diskette. (A granule, 
1280 bytes, is the unit of space allocation.) It also shows the location of the 
directory and any flawed sectors. 

When a diskette has been used extensively (file updates, files killed, extended, 
etc.), files often become segmented (dispersed or fragmented). This slows the' 
access time, since the disk read/write mechanism must move back and forth 
across the diskette to read and write to a file. 

free helps you determine just how segmented your disk files are. If you decide 
you'd like to re-organize a particular file to allow faster access, you can then 
copy it onto a relatively "clean" diskette. 
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Examples 

FREE 

Displays a free space map of the diskette in Drive 0. 

FREE (PRT) 

Lists the free space for Drive to the Printer. 

FREE :I (PRT) 

Lists the Drive 1 map to the Printer. 

A lypical FREE Display 

Four special symbols are used in the free map. 
• Unused Granule 

Direct Directory Information 
X Allocated Granule 

Flawed Granule Contains a Flawed Sector (Unusable) 

A typical free map display is shown in Figure 12. 



Disk Name 



All six granules in 
track 2 are allocated 




Figure 12. Free Map 



The directory is located 
on track 17. 



HELP 

Explanation of TRSDOS Command 



help command 



wmmandls the specific trsdqs command or subject on which you need 
help. If omitted or if an invalid subject is given, trsdos will list all 
available subjects. 



51 




TRS-80 MODEL III DISK SYSTEM 



Example 

If you type in the following: HELP BACKUP (INTER] trsdos will respond with 
the syntax format, a definition of the command, and an explanation of 
the abbreviation. 

HELP SYNTAX tells trsdos to explain the hitp descriptions. 



KILL 

Delete a File or Group of Files 



Two syntaxes: 



A) kill file 

file is a file specification 

B) miL/extd 

lextis a file extension that must contain three characters. 
:d is a drive specification. It must be provided. 



This command deletes one file or a group of files, depending on which form is 
used. Form A deletes the specified file. If no drive specification is given, 
trsdos deletes the file from the first diskette that contains it. 

Form B deletes all files with a specified extension, regardless of the file name of 
each file. If no drive specification is given, the files will be deleted from the first 
drive that contains a matching file specification. 

Examples 

KILL TESTPROG/BAS 

Deletes the named file from the first drive that contains it. 

KILL JOBF I LE/ I DY, PASSWORD: 1 

Deletes the named file from Drive I . The file has a password of password. 

KILL /BAS:(3 

Deletes from Drive all files having the extension bas. 
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LIB 

Display Library Commands 



LIB 



This command lists to the Display all the library commands. For help with a 
command, use help. 

Example 

LIB 



LIST 

List Contents of a File 



im file (mT,$im, asch) 

file is the file specification. 

?m tells TRSDOS to list to the Printer. If omitted, only the Video Display is 
used. 

sum tells irtsftos to pause briefly after each record. If omitted, the listing is 
continuous. 

AiHitelteRSDOs to list the file in asch format. If omitted, hexadecimal 
format is used. 



This routine lists the contents of a file. The listing shows both the hexadecimal 
contents and the asch characters corresponding to each value. For values 
outside the range (X'20\ x^f 1 ), a period is displayed. 

Use the asch option for text files and basic programs saved with the a option. 

Note: Only ascii codes xw-x^F' are sent to the Printer. Bit 7 is always 
set to 0. 

During the listing, press (@) to pause, CENTER) to continue, or (BREAK) to exit. 
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Examples 

LIST DATA/TXT (ASCII ) 

Lists the contents of data/txt in ascii format. 

LIST FILE/A (SLON) 

Lists the contents of fiee/a, pausing after each record. 

LIST PROGRAM/CMD (PRT) 

Lists the file program /cmd to the Printer. 

LOAD 

Load a Program File 



load file 

Hie is a file specification for a file created by the dump command 



This command loads a machine-language program file into memory. After the 
file is loaded, trsdos returns to the trsdos ready mode. 

You cannot use this command to load a basic program or any file created by 
basic. See the basic Reference Manual for instructions on loading basic 
programs. 

Note: The file must load into the user area (X'7000'-top). 

Examples 

LOAD PAYROLL/ PT1 

Sample Use 

Often several program modules must be loaded into memory for use by a master 
program. For example, suppose payrouvpti and payroee/pt2 are modules, and 
menu is the master program. Then you could use the commands: 

LOAD PAYR0LL/PT1 
LOAD PAYR0LL/PT2 

to get modules into memory, and then type: MENU to load and execute menu. 



54 



TRSDOS 




MASTER 

Set Master Read/Write Drive 



MASTER (DH1Vi = a) 

a is the drive specification. If omitted Drive is set as the master drive, 



This command allows you to assign a specified drive as the Master Read or 
Write drive in the system. When searching for a file, trsdos will start with the 
master drive. 

If the file is not found on the specified drive, trsdos will continue searching on 
the next higher-numbered drive. 

Example 

After you enter the command: MASTER (DRIVE = i) Drive 1 becomes the 
master drive. 



PATCH 

Change the Contents of a Disk File 



^k^p'Ui^= : ^a K fmn = bb,cm - cc) 

///^ is the file specification 

add -aaaa specifies the address at which the data is found, aaaa is a four- 
digit hexadecimal number. 

find ~bb specifies the string you wish to find (or compare to), bb is a 
hexadecimal sequence. 

chg = <# specifies the new contents for the byte(s). cc is a hexadecimal 
sequence. 

Note: This utility is for machine language programs only. 
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This command lets you make minor corrections in any disk file, provided that: 

1 . You know the existing contents and location of the data you want to change. 

2. You want to replace one string of code or data with another string of the 
same length. 

You can use patch to make minor changes to your own machine-language 
programs; you won't have to change the source code, re-assemble it, and re- 
create the file. 

Another application for patch is to allow you to implement any modifications to 
trsdos that may be supplied by Radio Shack. That way, you do not have to 
wait for a later release of the operating system. 

Sample Use 

Suppose you want to change seven bytes in a machine-language program file. 
First determine where the seven-byte sequence resides in ram when the program 
is loaded. Then make sure your replacement string is the same length as that 
of the original string. For example, you might write down the information 
as follows: 

File to be changed: vread 

Start address: x'528(r 

Sequence of code to be changed: x , CD2D25E.v 

Replacement code: x* 00000009* 

Then you could use the following command: 

PATCH VREAD ( ADD=528B >FIND=BCD2D25E5 >CHG=00000009) 



PAUSE 

Pause Execution for Operator Action 



pause message 



message is the message to be displayed during the pause execution. Ihis 
is optional. If omitted, pause will be displayed by itself. 
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This command is intended for use inside a do file so trsdos can print a message 
or reminder. 

To continue after the pause, trsdos prompts you with the message: 

PRESS < ENTER) TO CONTINUE 

Example 

PAUSE INSERT DISKETTE #21 

trsdos displays pause, next the message and then prompts you to press CENTER) 
to continue execution. 

PAUSE 

PRESS < ENTER)- TO CONTINUE 




trsdos displays pause and then next prompts you to press (ENTER) to continue. 
See build and do for sample uses. 



PROT 

Use or Change a Diskette's Master Password 



PROT;tf(PW,LOCK) 

: d is an optional drive specification. If omitted, Drive is used. 

m tells trsoos you want to change the master password. 

lock tells trsdos to assign the master password to all unprotected user 
files. If omitted, the unprotected files remain unprotected. 



prot lets you use the master password to protect all unprotected files at once, or 
to change the master password. 

The master password will be needed to backup the diskette, so be sure to 
remember it! 

Note: The master password on the trsdos factory-release diskette is password. 
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Examples 

PROT s(3 ( PW 



Tells trsdos to change the master password on the Drive diskette, trsdos will 
prompt you first for the old master password, then for the new master password. 



PROT si (LOCK) 

Tells trsdos to as: 

will first prompt you for the master password 



Tells trsdos to assign the master password to all unprotected user files, trsdos 
will first nromnt vou for the master password. 



PURGE 
Delete Files 



purge :d (file-type) 

:tf is the drive whieft contains the disk to be purged. 

file-type must be one of the following: 

sys Ali System and User files (no Invisible) 
m All Invisible and User files (No System) 
all All files on disk (User, System, Invisible) 

If file-typen omitted; trsdos defaults to User files. 



This command allows quick deletion of files from a particular diskette. To use 
purge, you must know the diskette's master password, (trsdos System 
diskettes are supplied with the password password.) 

When the command is entered, trsdos will ask for the diskette's password. 
Type in up to eight characters. Press CENTER] if you typed fewer than eight 
characters. The System will then display user filenames one at a time, 
prompting you to kill or leave each file. 

Example 

PURGE :1 

trsdos will purge user files from Drive 1 . This would include basic programs. 

PURGE :1 (I NY) 

trsdos will purge all invisible files in Drive 1 . 
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Note: System diskettes contain some files which are not shown in any of the 
directory listings. You may delete these files with a special form of purge: 



mm* :d (file-type) 



The asterisk tells trsdos to ask you if you want to delete the System files. If 
you do delete them, the diskette becomes a data diskette and may only be used 
in Drive 1, 2 or 3. 

The other parts of this command are as explained previously. However, be sure 
to do the purge using Drive 1, 2 or 3, since the diskette will become ' 'non- 
system' ' during the purge. 

RELO 

Change Where Program Loads into Memory 



file is the file specification, 
the user area of ram. 



This command allows you to change the address at which the program loads into 
memory. It does not change the program itself. 

Note: This command may be useful in conjunction with dump. 

Example 

RELO PROGRAM/CMD (ADD=G578) 

trsdos will load the program program/cmd at the new memory address 
of 6578. 
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RENAME 
Rename a File 



atdfiame is the did file name. 

wwmme is the new file name. 

The file name may Include a drive specification and or password. 

The new file nams should not include a drive specification or password. 



This command lets you rename a file or program. Only the name/extension 
is changed; the data in the file and its physical location on the diskette 
are unaffected. 

rename cannot be used to change a file's password protection. Use attrib 
to do that. 

rename also checks to see that the intended new name does not duplicate a 
filename currently on the same diskette. If it does, the command is cancelled 
and an error message is displayed. 

Examples 

RENAME MATHPAK MATHPAK/BAS 

Tells trsdos to add the extension to the filename. 

RENAME ABCDE/DAT ABCDEF/DAT 

Tells trsdos to change the filename only. 

RENAME PAYROLL 1 /TXT* GBR PAYR0LL2/TXT 

Tells trsdos to change the filename; the password is retained automatically. 

RENAME FILE1:3 FILE2 

Tells trsdos to change the filename of the file on Drive 3. 
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ROUTE 

Routing I/O Devices 



ROUTE ($0UBCe = 3a,D£$T!N ~ bb) 

source = aa specifies the source i/o device. 

destin = bb specifies the destination i/o device. 

aa and bb may be any meaningful combination of the following two-letter 
abbreviations: 



DO 


(Display) 


PR 


(Printer) 


KB 


(Keyboard) 


m 


(RS-232 Input) 


m 


(RS-232 Output) 



If the source and destination options are omitted, trsdos resets i/o Drivers 
to their original i o routes. The source and destination devices must both be 
output or both be input. 



This command allows you to route i/o devices automatically. For example, 
trsdos can route information from the Printer (PR) to the Display (DO). 

Note: route cannot be used in conjunction with the dual command. 



Examples 

ROUTE (SOURCE=PRtDESTIN=DO) 

trsdos will route your Printer output to the Display. 

ROUTE 

f/o drivers are returned to their original state. 

For further details on routing i/o see "Routing Input/Output" in the 
Model III Manual. 
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SETCOM 

Set Up RS-232-C Communications 



setcom (off.woro = a.BAUD = *,stop = cparity = d,mode) 

word = a is the number of bit/byte desired, a must be either 5, 6, 7, or 8, 

and 9600. If omitted, the baud rate is not changed. 

stop =c specifies the number of stop bits, c must be either 1 or 2. If 
omitted, stop bits are not changed. 

parity =rf determines whether the parity is odd, even, or none, d must be 3 



This command initializes rs-232-c communications via the serial channel. Before 
executing it, you should connect the communications device to the Model III. 

See the Model III Operation Manual for a description of rs-232-c signals used. 

See Using the RS-232-C Interface in the Model III Manual for further details. 

Examples 

SETCOM (WORD=7»BAUD=300»STOP=1 »PARITY=3 tWAIT) 

This would set the RS-232-c to seven bit words, 300 baud, one stop bit, no parity, 
and place it in the wait mode. 

SETCOM 

The command without specifications will display the current settings. 

The following program will allow you to use your Computer as a terminal. For 
further information, refer to the Operation section of your Model III Operation 
Manual. 

Note: This program executes at 300 Baud. 
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5 


DEFINT A-Z 


'INTEGER VARIABLE FOR SPEED 


10 


POKE 1G890* 


'DON'T WAIT FOR SERIAL I/O 


15 


POKE 16888* (5*16)+5 


'TX/RCU AT BAUD RATE 300 


20 


DEFUSRO = &H005A: REM 


BET UP CALL TO $RSINIT 


40 


X = USR0(0) 




B0 


DEFUSRI = &:H0050 




G5 


DEFUSR2 = &:H0055 




70 


CI = 16872 


'CHARACTER INPUT BUFFER 


80 


CO = 16880 


'CHARACTER OUTPUT BUFFER 


90 


' CHECK FOR SERIAL INPUT 


110 


X = USRK0) 


'CALL $RSRCV 


120 


C$ = CHR*(PEEK(CI) ) 


'LOOK AT INPUT BUFFER 


130 


PRINT C$ 


'IF C = 13. NOTHING HAPPENS 


140 


' CHECK FOR KEYBOARD 


INPUT 


150 


C$ = INKEY$ 




1G0 


IF C$ = "" THEN 110 


'NO KEY* SO GO CHECK SERIAL 


185 


PRINT C$: 


'SELF ECHO 


170 


POKE CO* ASC(C$) 


'PUT CHARACTER INTO OUTPUT BUFFER 


130 


X = USR2(0) 


'CALL $RSTX 


200 


GOTO 110 


'GO CHECK SERIAL INPUT 
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TAPE 

Tape/Disk Transfer 



tape (s = source, o = destination) 

soumemA destination are abbreviations for the storage devices to 
boused: 

t Tape 
o Disk 
n Random access memory 

Note: tape can only be used with machine-language programs, basic 
programs must be ciOAoed and csAVEed. 



This command transfers z-80 machine-language programs from one storage 
device to another. The following transfers are possible: 

• Tape to disk 
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• Disk to tape 

• Tape to ram 

Examples 

TAPE <S=TfD=D) 

Starts a tape-to-disk transfer, trsdos will prompt you CASS?. Select the desired 
baud rate (H for high, L for low), trsdos will then prompt you to press (ENTER! 
when the recorder is ready to play to the Computer. When you press CENTER] , the 
tape will begin loading. 

Note: If no asterisks flash, the recorder volume may need adjustment or the 
baud rate setting may be incorrect. 

trsdos will read the file name from the tape and use that name for the disk file. 
It will copy the program to the first write-enabled diskette, starting with the 
master drive (see master). 

TAPE (S=D»D=T) 

Starts a disk-to-tape transfer, trsdos will prompt you for the desired cassette 
baud r ate, then for the diskette file specification. Then it will tell you to press 
^NTER) when the cassette recorder is ready to record from the Computer. 

TAPE <S=T*D=R) 

Starts a tape-to-RAM transfer, trsdos will prompt you for the cassette baud rate, 
and will tell you to press (ENTER) when the recorder is ready to play to the 
Computer. After loading the program, trsdos will begin execution at the 
transfer address specified on the tape. 

TIME 

Reset or Get the Time 



imzhh:mm:$$ 

hh:mm:$$ specifies the hour hh, minute mm, and second $$. 

Each mm be a tw-riigit dermal number between the following ranges; 
hh 0-23 

mm 6-59 

$$ 0-59 
nhh:mm:$$\$ given, trsdos resets the time. 
If hh:mm:$s is not given, trsdos displays the current time. 
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This command lets you reset or display the time. 

Time uses a 24-hour clock. For example, 1:00 P.M. is displayed as 13:00. 

You initially set the time when trsdos is started up. After that, trsdos updates 
the time automatically, using its built-in clock. 

When you request the time, trsdos displays it in this format: 14 s 15 s 31 for 
2:15:31 P.M. 

Examples 

TIME 

Displays the current time. 

TIME 13:20:00 

Resets the time to 1:20:00 P.M. 

Note: If the clock is allowed to run past 23:59:59, it will re-cycle to zero, the 
date will be incremented, and the clock will continue to run. 
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WP 

Write-Protect Via Software 



d specifies the disk drive to be protected, if omitted, all drives will be 
unprotected. 



Diskettes can be protected from being overwritten by this command. It is a 
software write-protect rather than a hardware write-protect (such as the write- 
protect tab on the diskette). 

Only one drive may be protected at a time. 

To unprotect a drive, making it accessible to writing, simply enter the command 
wp without options or with a different drive number specified. The wp command 
will not override a write-protect tab. 



65 



TRS-80 MODEL Ml DISK SYSTEM 



Examples 

WP (DRIME=i) 

trsdos will write-protect the disk in Drive 1 . 

WP 

trsdos will eliminate write-protection on all drives. 
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TRSDOS Utility Commands 

BACKUP 

Create an Exact Copy of an Original Disk 



rsaerr^a^ 



backup copies the contents of the source disk to the destination disk. This gives 
you a "safe" copy of the disk. Always keep an extra copy of data or programs 
you have stored on your disks. 

Note: Both source and destination diskettes must be write-enabled. 

trsdos will prompt you at each step after you type: BACKUP 

If you omitted the source/destination-drive numbers, trsdos will begin with the 
prompts: SOURCE DRIVE NUMBER. 

Type in the number of the drive that contains the source diskette and press 
(EWTER) . 

DESTINATION DRIVE NUMBER? 

Type in the number of the drive that will contain the destination diskette and 
press CENTER] . 

SOURCE DISK MASTER PASSWORD? 

Type in the password assigned to your source diskette. 

DISK CONTAINS DATA* USE DISK OR NOT? 
Type in Y (Yes) or N (No). 
DO YOU NISH TO RE-FORMAT THE DISK? 
Type in Y (Yes) or N (No). 
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If you specified the source/destination drives, trsdos will request the 
password, skipping the first two steps. 

trsdos will then take charge of formatting and verifying the destination disk as 
well as letting you know if there are any errors or flawed tracks. 

CONVERT 

Model I to Model III File Conversion Utility 



CONVERT 



Model I formatted diskettes cannot be used in the Model III Disk System. 
However, the convert utility can read a Model I diskette and copy its non- 
system files onto a Model III trsdos diskette. This diskette may then be used 
normally in the Model III Disk System. The original Model I diskette may still 
be used in a Model I Disk System, since it is unchanged by convert. 

convert does not convert or change data; it converts the file storage format. 
For this reason, Model I Disk basic programs may require slight changes before 
they will run properly in the Model III Disk System. Model I machine-language 
programs may require major or minor changes before they will run in the Model 
III Disk System, You may make these changes on the Model I diskette before 
using convert, or on the Model III diskette containing the converted files. 

For hints on program conversion, see: 

• Technical Information in this manual 

• Technical Information in the Model III Manual 

• The manual, Instructions for Converting Specified Model I Programs for use 
on trs-80 Model III. 

Drive Usage 

In two-drive systems, the files must be copied onto a Model III system diskette 
in Drive 0; in three- or four-drive systems, the files may be copied onto a data 
diskette in Drive 1, 2 or 3. 

During the conversion process, the Model I diskette is referred to as the 

' 'source"; the Model III diskette, the ''destination/' The source diskette cannot 

be in the same drive as that of the destination diskette. 
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Password Protection 

convert is designed to preserve the password security of each file that it 
transfers. To accomplish this and still allow the copying of protected files, 
convert follows different procedures depending on the access and update 
passwords on each file. 

In the simplest case, a file has blank access and update passwords. The copied 
file will be given blank passwords. (If you have a Model I Disk System with 
trsdos 2.3, you may use the prot command to remove all passwords from all 
files. This will simplify the convert process. Do this on the Model I system 
before you attempt to convert to Model III.) 

In another case, the access and passwords are different. If the access password 
is blank and the update is not, then trsdos will prompt you for the update 
password. If you know the update password, type it in. The file will be copied 
with access and update passwords set to the old update password. If you don't 
know the update password, simply press (ENTER) . The file will be copied with the 
access password set to blanks and the update password set to an unknown value. 

If the access and update passwords are not blank and they are not the same, 
trsdos will not copy the file , but will print the message , FILE SKIPPED, and 
continue with the next file in the source directory. 

Sample Use 

Get the Model I diskette ready. If you have a Model I Disk System with trsdos 
2.3, try to remove all passwords from all your files. This will prevent any 
problems with passwords. The password protection may be restored with the 
Model III attrib or prot commands after the conversion is complete. 

Using the Model III Disk System, you must always have a Model III tr sdos 
diskette in Drive 0. trsdos ready should be displayed. Type: CONVERT (ENTER) . 

The program will ask, SOURCE DR I YE?. Type in the number of the drive 
containing the Model I diskette, and press (ENTER) . Then the program will ask, 
DESTINATION DRIVE?. Type in the drive number and press (ENTER)- In two- 
drive systems, you must use Drive as the destination. 

During the conversion process, the name of each file will be displayed as it is 
copied. If password information is needed, trsdos will prompt you for it. If 
you know the update password, type it in and press (ENTER) . The file will be 
copied and given the same update password. If you do not know the update 
password, simply press (ENTER) , in which case the file will be copied and given 
an unknown update password. 

If a file name on the source diskette is already used on the destination diskette, 
trsdos will print this message: FILE EXISTS* USE IT?. If you type Y, 
trsdos will copy the file. The previous contents of the Model III file will be 
lost. If you type N, trsdos will skip the file, and get the next one from the 
Model I diskette. 
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FORMAT 

Prepare a Data Diskette 



format:*? 



:tf specifies the disk drive whleh contains the diskette to be formatted. If : 
Is omitted, imm$ will prompt 



This command lets you prepare data diskettes (either new or disks which contain 
undesired data or programs), leaving a maximum amount of space for your 
program and data files. 

Note: Data diskettes may only be used in Drives 1 , 2, and 3 except during a 

BACKUP Or FORMAT. 

format takes a blank (new or magnetically erased) diskette, records track/sector 
boundaries on it, then initializes it with and creates a directory. 

When format detects a non-blank diskette, it will display a warning message: 

DISK CONTAINS DATA t USE DISK OR NOT? 

Type Y (Yes) and press (ENTER) if you do want to reformat, N (No) and press 
(ENTER) if you want to save the disk information. 

format will lock out any defective tracks to prevent data from being lost in 
these areas. 

If you begin to get read errors during access, reformat the disk. 



Example 

FORMAT ; 1 

After you are prompted for DISKETTE NAME? and MASTER PASSWORD?, 
trsdos will format Drive 1 . 
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HERZ50 

Set Up for 50 Hz AC power (non-USA users) 



starts Vm utility to change the system for 50 Hz operation, mmm is a bo- 
■: : :>r- fife. 



This utility is provided for customers in areas where the AC power is 50 rather 
than 60 Hz. It should not be used by any other customers, herzso simply places 
a patch on the diskette that changes the clock speed for 50 Hz users. 

herzso is a do file that makes a change in the software of trsdos. Only the 
Drive diskette is changed. Be sure it is write-enabled before you start the do- 
file. Once the herzso change is done, it will remain in effect for that diskette. 

To perform the change, type: 

DO HERZ50 

Once the change has been made, you will need to reset the system to put the 
change into effect. This loads the new software into ram. 



LPC 

Line Printer Control 



LPC 



The lpc utility program allows trsdos to ignore multiple carriage return 
commands. Without lpc, a top-of-form (LPRiNTCHR$(i2)) command will add an 
extra carriage return/line feed each time it is executed. Also, lpc masks the high 
bit of each data byte, allowing you to send certain intercepted codes to the 
printer. For instance, the basic statement lprintchr$o40) will send code 140- 
128= 12 (LPRiNTCHR$(i2)) to the Printer. 
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The printers that require lpc are: 

Line Printer III (26-1156) 
Line Printer VI (26-1166) 
Daisy Wheel WP50 (26-1157) 
Qume Daisy Wheel (26- 1157 A) 
Daisy Wheel II (26-1158) 

and all future printers. 

Printers that do not require lpc: 

26-1150, 1152, 1153, 1154, 1159, and the a version of lpiii (26-1 156A). 

You must load the lpc program before you load an application program. The 
easiest way to do this is to copy lpc onto your data/program diskette and then 
use the auto command to load lpc automatically each time you use the system. 
For instance, type: 



COPY LPCsi :0 (ENTER) 

Then, to make lpc an auto command on the diskette, type: 



AUTO LPC/CMD CENTER! 

Whenever you use your program diskette, lpc will automatically load into 
memory and you can use the program as usual. 

lpc locates into the highest available memory. There is no need to set MEMORY 
SIZE to protect lpc. It "hides" itself. However, you still need to set memory if 
required by your application program, lpc will be killed if the clear command 
is used. 

Warning: Once the lpc utility program is loaded and installed, you should not 
reload it except after a reset. Reloading re-installs the program and uses up more 
space each time! lpc will not execute if the Printer has been routed elsewhere. 
Also, if lpc has been executed and then the Printer is routed elsewhere, the 
original printer driver will regain control after the routing. 

MEMTEST 
Test Memory 



MRSfiSf 



This program tests your Model Ill's memory (read only and random access). In 
trsdos ready, just type MEMTEST and press (ENTER) . 
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The program automatically tests all memory locations, no matter what memory 
size you have. First it checks read only memory (rom); if everything is okay, it 
automatically goes on and checks random access memory (ram). If all ram 
checks out okay, the program continues. 

If the program detects a rom or ram error, it will display a detailed message. 
Repeat the test to make sure it is a valid error condition. Write the message 
down and contact your nearest Radio Shack for assistance. 

Note: memtest changes the entire contents of ram. Before running it, be sure 
you have saved any valuable code you may have in ram. 




XFERSYS 

Transfer System Files 



XFERSYS 



xfersys lets you upgrade your version of Model III trsdos by copying all 
system files from a new release diskette (source) onto a previously released 
diskette (destination) (i.e., version 1.2 to version 1 .3, etc.). 

System files which already exist on the destination diskette are replaced by those 
from the source diskette. Files which do not exist on the destination diskette are 
added. User files (program and data) are unaffected. 

Steps to upgrade a diskette 

Make backup copies of all diskettes to be upgraded. This is an important 
precautionary step. These backup copies should be kept until the upgrading 
process is complete and confirmed. 

Note: Both source and destination diskettes must be write-enabled. 

Insert the new release of trsdos into Drive and press the reset button. Then 
type XFERSYS CENTER) . 

After the program heading appears, trsdos will prompt you with DISKETTE TO 
CONVERT READY IN DRIVE i ( Y/Q )?. Type Y (yes) or Q (quit) and press 
[ENTER) . 

The upgrading process will then take place. When the process is complete, 
trsdos will tell you so and take you back to trsdos ready. 

Note: If an error occurs, including your trying to upgrade a non-system diskette, 
the operation will be cancelled and take you back to trsdos ready. 
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granules after the one containing the file's eof mark, are recovered and returned 
to the system when the file is closed. 



ATRSDOSfile 

FILE: 



LRN1 



LRN2 



LRN3 



EXTENT 1 



LRNN 



EOF 



EXTENT 2 



SEGMENT: GRANULE 1 



GRANULE 2 



GRANULE 32 



GRANULE: 



SECTOR X 



SECTOR X + 1 



SECTOR X + 2 



BYTE1 


BYTE 2 


BYTE 3 




BYTE 256 



SECTOR: 

LRN: Logical Record Number, used to specify an individual, user-defined 
logical record. Such a logical record is the smallest unit of 
information which can be addressed during disk input/output (a 
physical record is the unit which is actually read from or written to 
disk). 

File: A group of logical records; the largest unit of information which can 

be addressed by a trsdos command. 

Sector: A physical record, composed of 256 contiguous bytes. 

Granule: The minimum allocatable unit of storage for any file. 

Extent: One contiguous allocation of granules. 

System Routines for Assembly-Language I/O 

This information is provided for customers who wish to write their own 
assembly level i/o routines. An explanation of the calling sequence and 
parameters for each necessary i/o routine is given. A knowledge of z-80 machine 
code is assumed. 

The following notations are standard in this section: 

(HL) = xxxx Registers hl contain the address of (point to) xxxx in machine 
format. (If address of xxxx = 34B2H then the values in the 
registers are: h = 34; l = B2). Other register pairs will also be 
indicated this way. 

a = xx Register a contains the numeric value of xx in binary form. 

Register a is used to return the trsdos error code for i/o calls. 
A complete list of error codes and their meanings appears at 
the end of this chapter. Other registers will also be indicated 
this way. 
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DCB while $OPEN 



Address 


Length 


Explanation 


DCB + 


3 


Reserved 


+ 3 


2 


Physical Buffer address (lsb/msb) 


+ 5 




Offset to delimiter at end of current record 


+ 6 




File drive number residence 


+ 7 




Reserved 


+ 8 




eof offset of last delimiter in last physical record 


+ 9 




lrl (logical record length) 


+ 10 


2 


nrn (next record # — $open sets = x'ooocr — lsb/msb) 


+ 12 


2 


ern (ending record # — (last in file) lsb/msb) 


+ 14 


50 


Reserved 



NRN Next Record Number defines which record is to be read or written by the 
next system call for $read or $write. It is automatically incremented by one 
after each system call. In order to process random files, use the $posn call to 
direct trsdos to the record you wish to transfer next. 

ERN Ending Record Number is the last record number currently in the file. It 
is put into the directory at $close time, so if it is expected to be correct, the user 
must close his files after adding records to a file. This value may also be used to 
position to end of file so that new records may be added to the end of the file. To 
position to the end of file use a call to $posn with a record number of ern + l . 
$posn is described later. 

Physical and Logical Records in TRSDOS 

A physical record is defined as one sector of disk. One sector of disk contains 
256 user data bytes. The artificial term '"granule" is defined to be 3 sectors of 
disk space. There are 6 granules on each of the 40 tracks on the disk. A granule 
is the least amount of space allocated by trsdos. For programming purposes, 
the physical records in a file are numbered from to N. The largest record 
number (N) in a file will then be 3 times the number of granules allocated minus 
one ((3*G) - 1). All trsdos granule allocations are made as needed at the time 
of write, not when the file is created. 



Bytes 



Sectors 



Granules 



Tracks 



Disk 



. 256 


1 


— 


— 


768 


3 


1 


— 


4608 


18 


6 


1 


184320 


720 


240 


40 



Disk Space Table: For each 5 l A' f Disk Drive 

A logical record is defined by the user of trsdos. It may be anywhere from 1 to 
255 bytes in length. Once a file is opened with a specific lrl (Logical Record 
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Length), the length is fixed until the file is closed. To change a file's lrl, you 
must close it and re-OPEN it with the new lrl. 

Each opening of the file sets a single, fixed record-length, trsdos will "block" 
logical records into (or from) one physical record for maximum space utilization 
on the disk. 

Blocking is putting more than one logical record into one physical record. For 
instance, four 64-byte logical records will fit into one 256-byte physical record. 
A logical record may be broken into two parts by trsdos in order to fill the last 
portion of one physical record entirely before beginning to use the next physical 
record (i.e. records are spanned). This occurs when the physical record length is 
not an even multiple of the logical record length. 

If the user wishes to do his own blocking, he may specify a logical record length 
of bytes at the time of init/open and must himself manage the contents of the 
physical record buffer area of 256 bytes, trsdos will not move a logical record 
for the user if lrl = 0; in this particular case it will only read/write the physical 
record to/from the buffer. Once control is shifted to your program, you will have 
about 20 bytes of stack size left. 

Fundamental TRSDOS I/O Calls 

There are 17 fundamental trsdos routines involved in handling file i/o. These 
are: 

$BACKSPACE $POSN 

$CLOSE $PUTEXT 

$DIVIDE SRAMDIR 

$DMULT $READ 

$FILPTR $REWIND 

$INIT $SYNTAX 

SKILL $VERF 

$OPEN $WRITE 
$POSEOF 

The detailed calling sequences and discussions for each of these routines follow. 
Note that all of these system calls use register f and do not restore its value 
before return. In order to apply this data properly, you should read through all of 
these descriptions and clear up all of the points that are not obvious to you by 
using other reference materials. If you are successful in doing this you will find 
that trsdos is a workable tool for your programming ideas. 

$INIT— 17440/X'4420' 

$init is provided as an entry point to trsdos which will create a new file entry 
in the directory and open the dcb for this file. $init scans the directory for the 
filespec name given in the dcb. If the filespec name is found, $init simply opens 
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the file for use. If the name is not found, a new file is created with the filespec 
name. 

Entry Conditions 

(HL) = buffer (see beginning of this section for notation) 

(DE) = DCB 
B = LRL 
CALL $INIT 

Exit Conditions 

iy — changed 

z = OK 

c carry flag is on if a new file was created 

a = trsdos error code. (Error codes listed at end of this chapter) 

$OPEN— 17444/X'4424' 

$open provides a way to open the dcb of a file which already exists in the 
directory. The dcb must contain the filespec of the file to be opened before entry 
to $open. 

Entry Conditions 

(HL) = BUFFER 
(DE) = DCB 
B = LRL 
CALL $OPEN 

Exit Conditions 

Z = OK 

z = if file does not exist. 
a = trsdos error code. 
iy = changed 



$POSN— 17474/X'4442' 

$posn positions a file to read or write a randomly selected logical record. Since 
it deals with logical records, the proper computation is done to locate which 
physical record(s) contain the data. Following a $posn with a $read or $write 
will transfer the record to/from ram. 
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in order to satisfy the request, it will do so. "Spanning" will be handled by 
trsdos as necessary. At $init $open time the dcb value of nrn is set to x'oooo* 
so that the first record will be written. After each logical record is transferred, 
the nrn value in the dcb will be incremented by 1 . 

If lrl = o, $write transfers one physical record from buffer into the disk file 
using the nrn in the dcb. buffer is defined at $init/open time only. The dcb 
value nrn is updated as above, after the write. 

Entry Conditions 

(HL) = urec if lrl is not zero. Unused if lrl = o 
de = dcb 
call $write 

Exit Conditions 

Z = OK 

a = trsdos error code. 



$VERF— 17468/X'443C' 

The only difference between $verf and $write is that $verf writes one physical 
record to disk and then reads it back into a special trsdos ram area not defined 
by the user. This special area and the original write buffer are then compared 
byte by byte to assure that the record was successfully written. 

Entry Conditions 

(HL) = Same as $write above. 

(DE) = DCB 
CALL $VERF 

Exit Conditions 

Z = OK 

a = trsdos error code. 



$PUTEXT— 17483/X'444B' 



This routine will add an extension to a filename if an extension does not already 
exist. An extension to a filename may be useful for identifying the type of data 
in the file. 
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Entry Conditions 

(DE) = DCB 
CALL $POSEOF 



Exit Conditions 

z = Good file specification 
nz = Bad file specification 



$SYNTAX— 17436/X'441C' 

Move a file specification to dcb. This routine takes a file specification and 
checks it for validity and moves it to a dcb so that the file may be opened. 

Entry Conditions 

(HL) = Filename 

(DE) = DCB 
CALL $SYNTAX 



Exit Conditions 

z = Good file specification 
nz = Bad file specification 



$DIVIDE — 17489/X'4451 ' 

The divide routine takes a 16-bit dividend and an eight-bit divisor. After 
division, the quotient replaces the 16-bit dividend and the remainder replaces the 
eight-bit divisor. 

Entry Conditions 

hl = Dividend 
a = Divisor 

CALL $DIVIDE 



Exit Conditions 

hl = Quotient 

a = Remainder (0 indicates no remainder). 
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$DMULT — 17486/X'444E' 

The multiply routine uses a 16-bit multiplicand and an eight-bit multiplier. After 
multiplication takes place, the product replaces the 16-bit multiplicand. 

Entry Conditions 

hl = Multiplicand 
a = Multiplier 

CALL $DMULT 

Exit Conditions 

h = High order byte 
l = Middle order byte 
a = Low order byte 

H L A 



High Middle Low 



$RAMDIR— 17040/X'4290' 

This routine allows you to examine a diskette directory (one entry or the entire 
directory) or the diskette's free space. The information is written into a user 
specified ram buffer. 

Only non-system files will be included in the ram directory. 

Entry Conditions 

hl - ram Buffer. If c = 0, size = 1761 [max #*22+ 1]. If c=i to 96, 

size =22. If c = 255, size = 64. 
b = Specified drive number 
c = Function switch: 



Contents of C 



1-96 

255 

CALL $RAMDIR 



Results 

Gets entire directory into ram. (See ram Directory Format). 

Gets one specified directory record into ram, if it exists. (See 
ram Directory Format). 

Gets free-space information (See ram Directory Format). 



Exit Conditions 

nz = Error occurred. 

z — No error. (HL) = directory or free-space information. 
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RAM Directory Format 

The directory is made up of records, one per file. All values are hexadecimal. 
Each record placed in user ram is in the following format: 

Byte Number Contents 

0-14 filename/ ext:d (left-justified followed by spaces) 

15 Protection Level, binary 0-6 

16 Byte eof, binary 0-255 

17 Logical record length, binary 0-255 
18-19 Last sector number in file, binary lsb, msb 
20-21 Number of Granules allocated (LSB,msb) binary 

22 " + " (marks the end of directory list after entire directory.) 

Free Space Message Format 

***nnnnn Free Granules*** 

Where nnnnn is a decimal number. The entire message is ASCII-coded. 

$FILPTR— 17037/X'428D' 

This routine provides information on any user file that is currently open. It 
enables you to obtain the drive number and the logical file number for any file 
and should be used in conjunction with $ramdir. 

Entry Condition 

(DE) = Data Control Block (dcb) defined when file was opened. 

CALL SFILPTR 

Exit Conditions 

nz = Error occurred. 

z = No error. The following registers are set up: 
B = Which drive contains the file (0,1,2, or 3). 
c = Logical file number (1-96) 

Note: This operates with user files only. 

$CLOSE — 17448/X'4428' 

$close closes a file from the last processing done. It is very important to do 
a $close on every file opened before the program ends. If you do not close 
a file, the directory entry for this file is incorrect if any new records have been 
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$D ATE — 12339/X'3033' 
$TIME— 12342/X'3036' 

These routines return the date and time in ascii format: 

Date: mm/dd/yy 
Time: hh/mm/ss 

Entry Conditions 

(HL) = Eight-byte buffer to receive the date/time text 

CALL $DATE 
CALL $TIME 

Exit Conditions 

(HL) = Date or time text 

$DATLOC — 16922/X'421 A' 
$TIMLOC — 16919/X'4217' 

These locations store the date and time in binary format: 

$datloc (Three bytes): yy dd yy 
$timloc (Three bytes): ss mm hh 

$ERRDSP— 17417/X'4409' 

This routine displays a trsdos error message determined by the contents of the 
accumulator (A). This register contains an error code (0 = no error) after 
completion of any system routine. 

Entry Conditions 

a = trsdos error code (see Table at the end of this section). In a trsdos error 
code, bits 6 and 7 are normally reset (off). So serrdsp interprets them as 
controls. 

Not Set (Normal 
Bit # Set Condition) 

7 Return to caller upon Return to trsdos upon 

completion completion 

6 Give detailed error message Give error number only 

call $errdsp 
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$CMDDOS— 17052/X'429C 

This routine executes a trsdos command and returns to the caller. 

Entry Conditions 

(HL) = Text of trsdos command, terminated by xod: 

Exit Conditions 

All registers are changed. 

Caution: trsdos commands will overlay ram up to x'6FFF/ 

$CMDTXT — 16933/X'4225' 

This is the start address of a buffer containing the last command line entered 
under trsdos ready. Using this buffer, your program may recover parameters 
that were included in the last command line. 

For example, given a program named editor/cmd, we want the operator to 
select an input file name when the program is loaded and executed from trsdos 
ready: 

trsdos ready 
editor myfile 

The program, editor, can recover the name of the file in the scmdtxt buffer. 

Note: On entry to a program, (hl) = First non-blank character following the 
program name. 

$MEMEND— 17425/X'4411' 

This storage location contains the highest address available. It is normally the 
same as the physical end oPram, but you may change it for special purposes. 

The address is in lsb, msb sequence. 
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TRSDOS Error Codes/Messages 

No Error Found 

1 CRC Error During Disk I/O 

2 Disk Drive Not In System 

3 Lost Data During Disk I/O 

4 CRC Error During Disk I/O 

5 Disk Sector Not Found 

6 Disk Drive Hardware Fault 

7 **Undefined Error Code** 

8 Disk Drive Not Ready 

9 Illegal I/O Attempt 

10 Required Command Parameter Not Found 

1 1 Illegal Command Parameter 

12 Time Out On Disk Drive 

13 I/O Attempt To Non-System Disk 

14 Write Fault On Disk I/O 

15 Write. Protected Disk 

16 Illegal Logical File Number 

17 Directory Read Error 

18 Directory Write Error 

19 Invalid File Name 

20 GAT Read Error 

21 GAT Write Error 

22 HIT Read Error 

23 HIT Write Error 

24 File Not Found 

25 File Access Denied Due to Password Protection 

26 Directory Space Full 

27 Disk Space Full 

28 Attempt to Read Past EOF 

29 Attempt to Read Outside of File Limits 

30 No More Extents Available 

31 Program Not Found 

32 Invalid Drive Number 

33 "Undefined Error Code" 

34 Attempt to Use Non-program File as a Program 

35 Memory Fault During Program Load 

36 "Undefined Error Code** 

37 File Access Denied Due to Password Protection 

38 I/O Attempt to Unopen File 

39 Invalid Command Parameter 

40 File Already In Directory 

41 Attempt to Open File Already Open 
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Introduction 

Start-Up 

Under trsdos ready, type: 



BASIC fENTER) 

trsdos will load basic and begin the "initialization dialog." 

If you want to recover a Disk basic program after returning to trsdos for a dir 
or other trsdos command, use this command under trsdos ready: 

BASIC * (ENTER] 

You will go directly to Basic's ready mode without any initialization dialog. If 
you had a program in memory, it should still be there. You may not be able to 
run the program. To be safe, you should immediately save the program, go to 
trsdos, then start basic again (no asterisk). 

Note: If you have overlaid user memory while in trsdos, your program will be 
erased. In such a case, you should not restart basic, but should use the normal 
basic start-up procedure. 



Initialization 

When you start Disk basic, you are first asked, HON MANY FILES?. This lets 
you specify the maximum number of files that will be "open " or in use at once. 
(See open.) Type in an appropriate number and press (ENTER), or simply press 
(ENTER) and basic will provide for three files. 

For example, if your program requires one input file and one output file, you 
should ask for two files. 

Note: Normally, basic will give all your data files a record length of 256. 
(See File Access Techniques.) If you wish to set the record length of each file 
individually, use the suffix v for "Variable" after the number of files. 
For example, 

HON MANY FILES? 3U fENTER) 

tells basic to give you three file-buffers, and to let you set the record length of 
each file when that file is first opened. 

Note: Disk basic automatically creates a buffer for loading, saving, and 
merging basic programs. This buffer exists in ram below any data file buffers 
you may request. It is always available for program i/o, regardless of how you 
answer the files? question. 
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After you an swer the files question, basic will ask: MEMORY SIZE? Simply 
press (ENTER) without typing a number. You will then have the maximum amount 
of ram available for use by basic. 

If you will want to load and use machine-language programs or routines, you 
will have to protect your basic memory from these machine-language programs. 

In such a case, respond with the highest memory address (in decimal form) you 
want basic to use for storing and executing your basic programs. Addresses 
above the number you specify will then be protected from use by basic. 

Example: 



MEMORY SIZE? 32000 CENTER] 

causes basic to protect addresses above 32000. If you have 16K of ram, this 
means that you'll have 32767-32000 = 767 bytes protected for storing your 
machine-language routines. 

After you answer the MEMORY SIZE? question, Disk basic will display the 
following information: 

1 . Which version of Disk basic you are using 

2. Copyright information 

3. The number of free bytes available 

4. The number of concurrent files you have requested. 

To exit from Disk basic and return to the trsdos ready mode, type: 



CMD"S" [ENTER) 

This results in a normal return to trsdos, without re-initialization of the system. 
You may recover your program if you haven't changed user memory while in 
trsdos. Use basic *. 
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Enhancements to Model m BASIC 

Disk basic adds many features which are not disk-related. They are listed below 
along with abbreviated descriptions. Detailed descriptions follow in alphabetical 
order. 



&H 

&o 
Abbreviations 

CMD'A" 

CMD"B" 

CMD"C" 

CMD'D" 

CMD'E" 

CMD"I" 

CMD"J" 

CMD"L" 

CMD'O" 

CMD'T" 

CMD"R" 

CMD"S" 

CMD'T" 

CMD"X" 

CMD"Z" 
DEFFN 
DEF USR 

INSTR 
LINE INPUT 
MID$ = 

NAME 

usrh 



Hexadecimal-constant prefix 

Octal-constant prefix 

Many commands have abbreviations 

Return to trsdos with error message 

Enable/Disable fBREAKl 

Delete spaces and remarks from a program (compression) 

Display directory for specified drive 

Display previous trsdos error 

Return a command to trsdos 

Convert calendar date 

Load z-80 subroutine or program file into ram 

Alphabetizes (sorts) a string array only 

Check printer status 

Start real-time clock display 

Normal return to trsdos (jump to exit routine) 

Turn off real-time clock display 

Cross-reference of reserved words, string variables, or 

strings in a program 

Duplicate output to Display and Printer 

Define BASic-statement function 

Define the entry point for an external machine-language 

routine 

Instring function; find the substring in the target string 

Input a line from keyboard 

Replace portion of the target string (used on left of equals 

sign) 

Renumber a program in ram 

Call external routine (n = 0,l,2, . . . ,9) 



&H and &O (hex and octal constants) 

Often it is convenient to use hexadecimal (base 16) or octal (base 8) constants 
rather than their decimal counterparts. For example, memory addresses and byte 
values are easier to manipulate in hex form. &H and &o let you introduce such 
constants into your program. 

&h and &o are used as prefixes for the numerals that immediately follow them: 
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■^■*iil!iM^^ '■■■■ ■ ■ : ""-- '"■■■"■■■'■" '"■ '.™^ 

(fcfcfcfis a 1 to 4 digit sequence composed of hexadecimal numerals 









I$|ffl^ &oddddd=&ddddd. 



The constants always represent signed integers. Therefore any hex number 
greater than &H7FFF, or any octal number greater than &077777, will be 
interpreted as a negative quantity. The following table illustrates this: 



Octal 



Hex 



Decimal 



&1 


&H1 


1 


&2 


&H2 


2 


&77777 


&H7FFF 


32767 


& 100000 


&H8000 


-32768 


&1 00001 


&H8001 


-32767 


&1 00002 


&H8002 


-32766 


& 177776 


&HFFFE 


-2 


& 177777 


&HFFFF 


-1 



Hex and octal constants cannot be typed in as responses to an input prompt 
or be contained in a data statement. Often the hex or octal constant must be 
enclosed in parentheses to prevent a syntax error from occurring. 

Examples 

PRINT &H5200, &O51000 

prints the decimal equivalent of the two constants (both equal 20992). 

POKE &H3C00, 42 

puts decimal 42 (ascii code for an asterisk) into video memory address hex 

3C00. 
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Abbreviation 


Meaning 


® 


List Previous Program Line 


© 


List Next Program Line 


CD 


List Current Program Line 


CD 


Edit Current Program Line 


[SHIFT) W 


List First Program Line 


(SHIFT) (♦) IZJ 


List Last Program Line 


LXX 


List Program Linexx 


EXX 


Edit Program Line xx 


DXX 


Delete Program Linexx 


AXXX,XXXX 


Automatic Line Numbering Beginning at Linexxx ; 




Incrementing byxxxx. 



CMD "A" 
Return to TRSDOS 















m{ 



This command allows you to return to trsdos with an error message: 

OPERATION ABORTED 

Sample Use 

After an input/output error occurs in a basic program, you might want to exit to 
trsdos and print a message. 

CMD "A" 

the following will be displayed: 

OPERATION ABORTED 
TRSDOS READY 
****************** 
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CMD "B" 

Enable/Disable BREAK Key 



%va» "euiHnh" 



switilih either on or off, switch must be enclosed in quotation rtiarks. 



This command enables or disables the (BREAK) key. While the function is "off," 
the (BREAK) key will be ignored except during cassette or printer output or during 
serial input/output. 



The (BREAK) key will remain disabled even after the program has ended. To 
enable the (BREAK) key, use the cmd-B'Y'ON" command. Returning to trsdos 
via the cmd'^S" or cmd"I" commands will also enable the (BREAK) key. 

Examples 

CMD"B M ,"0FF" 



Disables the (BREAK) key. 

CMD"B" *"0N H 



Returns the (BREAK) key to its normal function. 

CMD "C" 
Compress Program 



;43i6^ ,■■.■:■ /■- . 

? ^ spaces are deleted. If only one is 

■fjif)^^ action is taken. 



This command allows you to compress a program so that it requires less 
ram and less storage space on diskette. You can elect to remove all remark 
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statements (beginning with rem or ') or to delete all spaces between basic 
keywords. Spaces inside quotes will not be deleted. 

Example 

Your program reads as follows: 

850 RESTORE; ON ERROR GOTO 800 'DOG PROGRAM 

8G0 READ COMPANY* 'PET STORE 

870 PRINT RIGHT$(C0MPANY$*2) *: GOTO 8S0 
880 END 

If you want to delete the Remarks (lines 850 and 860), type in the command: 

CMD n C" tR 

and the program will now read: 

850 RESTORE: ON ERROR GOTO 800 

8G0 READ COMPANY* 

870 PRINT RIGHT$(C0MPANY$>2> *:G0T0 880 

880 END 

If you then wanted to delete the spaces, type in: 

CMD"C" *$ 

and the program would read: 

850 RESTORE : ONERRORGOTO800 

8S0 READCOMPANY$ 

870 PRINTRIGHT$(C0MPANY$*2> ,:GOTO860 

880 END 

You could obtain the same results by typing: 

CMD"C" 

Note: Always provide the closing quotes on string literals in your basic 
program. Otherwise cmd"C" may not function properly. For example, in 

10 PRINT "THIS IS A TEST" 

the second quote should be used even though omitting it will not cause an error. 

CMD"D" 

Display the Directory of a Specified Drive 



"D:d" 
6 is the drive specification 
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By entering the command cmd u d:J", you can obtain a specified diskette's 
directory from basic without returning to trsdos. Only unprotected, visible 
files will be displayed. The drive specification is not optional and must be 
specified for all drives, including Drive 0. 

Example 

If you type in the command; 

CMD n D:i" 

the directory for Drive 1 will be displayed. 

CMD"E" 

Display Previous TRSDOS error 



CMD"E" 



This command displays the last trsdos error message. If no errors have 
occurred prior to the command, the message NO ERROR FOUND will be 
displayed. 

Example 

If you have a two-drive system (0 and 1) and you type: 

SAVE "PROGRAM: 3" 

Disk basic will return a DISK I/O ERROR. To find out what kind of i/o error 
occurred, type: CND'-E" fENTERl and Disk basic will return with DISK DRIVE 
NOT IN SYSTEM. 

CMD'T" 

Execute TRSDOS Commands from Disk BASIC 



^ew^^ ■" , v ; 
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You may execute trsdos commands directly from basic by using cmd'T'. 

This is similar to cmd"S" , except that it lets you include a command or z-80 
program for trsdos to execute. 

As long as basic is not overwritten by the execution of the program or 
command, control will return to basic; otherwise, control will return to trsdos. 
(trsdos commands all overlay basic; your z-80 program may not if it loads 
above basic.) 

Example 

CMD" I" t M PROGRAM" 

returns you to trsdos and executes the program file program. 

CMD'T" >A$ 

returns you to trsdos and executes the command contained in a$. 

CMD'T 

Calendar Date Conversion 






This command converts dates back and forth between two formats: the standard 
month, day, year, sequence; and a year, day of year, sequence. The content of 
the source string determines which way the conversion goes. 
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Example 

CMD"J" t "11/30/80" » D$ 
Returns the day of the year in d$. 

CMD"J" * "-79/300" f D$ 

Returns the month, day, year, equivalent in d$ (the date for the 300th day 
of 1979). 

Sample Program 

10 CLEAR 50 

20 LINE INPUT'ENTER FIRST DATE (HM/DD/YY) "5 FD$ 

30 LINE INPUT'ENTER SECOND DATE (MM/DD/YY) " ?SD$ 

40 CMD"J" t FD$, Dl$ 

50 CMD"J" * SD$> D2$ 

60 Yl = VAL<RIGHT$(FD*»2>) 

70 Y2 = UAL(RIGHT$(SD$,2)) 

80 Jl = VAL(RIGHT$(D1**3) ) 

90 J2 = 0AL<RIGHT$<D2$*3>) 

100 SI = Yl*365 + Jl 

110 S2 = Y2*365 + J2 

120 PRINT "THE INTERVAL BETWEEN DATES IS" 5 

130 PRINT ABS(S1-S2); "DAYS " ! 

140 PRINT "(IGNORING LEAP-YEARS )♦ " 

150 INPUT "<ENTER> TO CONTINUE"! A$ 

1S0 GOTO 20 

CMD"L" 

Load Z-80 Routine into RAM 



mB'v\fQutme 



roiiiinek a string expression containifig a file specification for a z-so 
routine or program created by the dump command. If routine is a 
string constant, it must be enclosed in quotes. 



cmd"L" loads a z-80 (machine-language) routine into ram. It would normally 
be used to load a z-80 subroutine which is to be accessed directly from basic. 
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The z-80 routine should load into high-RAM and must not overlay the memory 
protect area reserved when you first entered basic (i.e., the MEMORY SIZE? 
prompt). If you do not overlay basic or trsdos, control will return to basic 
after the program is loaded. 

Example 

The command: 

CMD"L ,J ♦"PROG" 

will load a program file named prog into ram. 

CMD"L" >P$ 

will load a program which has been specified as p$. 




CMD"0" 

Sort ("Order") an Array 



'.'■■■ jt js\tm.'1iiid9er variable containing the number of Jfeih^to be;s.ort9d.; % ■ 

arrayfstert) specifies an array element. The array contains the data to be 
sorted, and start is the subscript of the first element to be sorted. The 
array must be one-dimensional, string type. The string elements in 
array may be of any length. 



This command sorts (orders) a one-dimensional string array, i.e., a list. You 
may sort all or part of the array, depending on the values you give to x and start. 

Sample Program 

10 CLEAR 10 * 25 + 50 'ROOM FOR 10 WORDS + EXTRA 

20 DIM A$(9) 'LIST OF TEN (0-9) 

30 FOR ND = TO 9 

40 PRINT "ENTER WORD #"5 WD+1 

50 INPUT A$(WD) 

S0 NEXT WD 

70 N*=iB: CMD ,, 0" t NX > A$(0) 

80 PRINT "HERE IS THE SORTED LIST" 

90 FOR WD=0 TO 9 
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100 PRINT A$(WD) 
110 NEXT ND 



CMD"P" 

Check Printer Status 



mDF\$tatus 

status is a string variable 



cmd"P" makes it possible for Disk basic to check the status of the printer. 

Unlike the video display, the printer is not always available. It may be 
disconnected, offline, out of paper, etc. In such cases, when you try to output 
information to the printer, the Computer will wait until the printer becomes 
available. It will appear to "hang up." To regain keyboard control (and cancel 
the printer operation), press (BREAK) . 

Suppose you have a program which uses printer output. If a printer is not 
available, you don't want the Computer to stop and wait for it to become 
available. Instead, you may want to print a message such as PRINTER 
UNAVAILABLE and go on to some other operation. 

To accomplish this, you need to check the printer status, cmd^p" can be used to 
check the printer's status at any time. It returns the contents as an Ascn-coded 
decimal number. The specific value of this number depends upon the type of 
printer you are using as well as its status at any particular time. The value may 
then be printed or examined by the program. 

Only the four most significant bits are used in this "status byte." In binary, 
these must be: "0011" or else the print operation will not be attempted. To 
check for this "go" condition, and the status byte with 240 and compare the 
result with 48. The meaning of each status bit depends on which printer you 
use. See the printer owner's manual for bit designations. 

Sample Program 

10 CMD"P" #X* 

20 SJ1 = UAL<><$) AND 240 

30 IF STZ <> 48 THEN PRINT "PRINTER UNAVAILABLE" : STOP 

40 PRINT "PRINTER AVAILABLE" 

50 REM PROGRAM MAY NOW CONTINUE 
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CMD"R" 

T\irn On Clock-Display 



This command controls the real-time clock display in the upper-right corner of 
the Video Display. When it is on, the 24-hour time will be displayed and 
updated once each second, regardless of what program is executing. 

Note: The real-time clock is always running (except during cassette or disk i/o), 
regardless of whether the display is on or off. 

Example 

To turn on the clock display type: CMD"R" To turn the display off, type: CMD"T n 

CMD"S" 

Return to TRSDOS 



CMD"S '! 



To exit from Disk basic, returning control to trsdos, simply type in the 
command: 

CMD"S n 

To return to basic and recover your program, use BASIC *. However, recovery 
will not always be possible. See basic *. 

Example 

The basic prompt lets you know you are in Disk basic. 

READY 
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To exit, type in: 

CHD I! S" 

and the trsdos prompt will appear. 

TRSDOS READY 



*************** 



CMD"T" 

Turn Off Clock-Display 



CWT* 



This command turns off the real-time clock display function. 
However, the clock continues to run. 

Example 

To stop the clock display update type: CMD 11 !"" 
To start the display, type: CMD"R" 

CMD "X" 

Cross-reference of Program Lines 



CMO^Vte/gef 



target is either a basic reserved word (such as print) or a sfriiig-literal. If It 
is a reserved word, it must not be enclosed in quotes; if it is a string- 
literal, it must be enclosed in quotes. 
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This command finds all occurrences of a reserved word or other string literal in 
the resident program. The " finds" are listed on the display as five-digit line 
numbers. 

To search for any basic reserved word (including reserved arithmetic operators), 
use the keyword as-is. To search for anything else (including variable-names and 
text), enclose the text inside quotes. 

For example, suppose you have the following program in memory: 

10 PRINT "THIS IS A TEST" 

20 INPUT "PRESS <EIMTER> FOR THE NEXT PRINT MESSAGE"; Z$ 

30 A = A + 1 

40 PRINT "+ ++4- + + +" 

CMD "X" t PRINT will find all occurrences of print, except for cases where 
print was part of a quoted string: lines 10 and 40. 

CMD "X" * "PRINT" will find all occurrences of "print" as a string literal: line 
20. 

CMD "X" , + will list line 30, but CMD "X% " + " will list line 40. CMD "X" * 
"A" will list lines 10, 20, and 30. Notice that variables and text are both treated 
as string literals. 

CMD "Z" 

Duplicate Output to Video and Printer 



€wrv "switch" 

switch is either on or off. switch must be enclosed in quotation marks, 



This command enables or disables dual video/printer output. While the function 
is "on," all video output is copied to the printer, and all printer output is copied 
to the video. (The printer must be on-line when you turn dual output "on.") 

Video and printer output may differ due to intrinsic differences in the printer and 
video devices. 




Examples 

CMD "Z" » "ON" 

Turns dual video/printer output on. 



105 




TRS-80 MODEL III DISK SYSTEM 



Turns dual video/printer output off. 

DEFFN 
Define Function 






formula 



function does. 

formula is an expression usually involving the argument(s) | 
the teM^ 



The def fn statement lets you create your own function. That is, you only 
have to call the new function by name, and the associated operations will 
automatically be performed. Once a function has been defined with the def fn 
statement, you can call it simply by inserting fn in front of function name. You 
can use it exactly as you might use one of the built-in functions, like sin, abs, 
and strings. 

The type of variable used for function name determines the type of value the 
function will return. For example, if function name is single precision, then that 
function will return a single-precision value, regardless of the precision of the 
arguments. 

The particular variables you use as arguments in the def fn statement 
(argument-1, . . .) are not assigned to the function. When you call the function 
later, any variable name of the same type can be used. 

Furthermore, using a variable as an argument in a def fn statement has no effect 
on the value of that variable. So you can use that particular variable in another 
part of your program without worrying about interference from def fn. 

The function can be defined with no arguments at all, if none are required. 
For example: 

DEF FNR = RND (9(3) + 9 

defines a function to return a random value between 10 and 99. 
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Examples 

DEF FNR(AtB) = A + INT((B - (A - 1)) * RND<0>> 

This statement defines function fnr which returns a random number between 
integers A and B. The values for A and B are passed when the function is 
"called," i.e., used in a statement like: 

Y = FNR(R1 * R2) 

If ri and R2 have been assigned the values 2 and 8, this line would assign a 
random number between 2 and 8 to y. 

DEF FNL$(K) = STRING*(Xf "-") 

Defines function fnl$ which returns a string of hyphens, x characters long. 
The value for x is passed when the function is called: 

PRINT FNL$<3) 

This line prints a string of 30 hyphens. 

Here's an example showing def fn used for a complex computation — in 
double-precision. 

DEF FNX#(A#* B#) = <A# - B») * (A« - B«) 

Defines function fnx# which returns the double-precision value of the square of 
the difference between a# and b#. The values for a# and b# are passed when 
the function is called: 

S# = FNX*(A#> B«) 

We assume that values for a# and b# were assigned elsewhere in the program. 

Sample Program 

71(3 DEF FNV(T> = (1S87 + SQR(273 + T))/1G # 52 
720 INPUT "AIR TEMPERATURE IN DEGREES CELSIUS"; T 
730 PRINT "THE SPEED OF SOUND IN AIR OF" T "DEGREES 
CELSIUS IS" FNV<T) "FEET PER SECOND*" 
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DEFUSR 

Define Point of Entry for USR Routine 



n equals one of the digits 0, 1 ,.,.,9; if n is omitted, is assumed. 



defusr lets you define the entry points for up to 10 machine-language routines. 
In non-Disk basic, the addresses were POKEd into ram. This poke method 
cannot be used in Disk basic. 

Examples 

DEFUSR3 = &H7DBB 

assigns the entry point X'7D00\ 32000 decimal, to the USR3 call. When your 
program calls USR3, control will branch to your subroutine beginning at x'7D00\ 

DEFUSR = (BASE + IS) 

assigns start address (base + 16) to the usro routine. 

Note: When decimal addresses are given, they are evaluated as signed two-byte 
integers. So, for addresses above 32767, use desired decimal address -65536. 
See usR/i. 

INSTR 

Search for Specified String 



position specifies the position in string 1 where the search is to begin. 
position is optional; if it is not supplied, search automatically begins 
at the first character in string 1. (Position 1 is the first character in 
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llllitlt^^ search for. 



This function lets you search through a string to see if it contains another string. 
If it does, instr returns the starting position of the substring in the target string; 
otherwise, zero is returned. Note that the entire substring must be contained in 
the search string, or zero is returned. Also, note that instr only finds the first 
occurrence of a substring at the position you specify. 

Examples 

In these examples, a$ = "Lincoln": 

INSTR(A$* "INC") 

returns a value of 2. 

INSTR <A$> "12") 

returns a zero. 

INSTR(A$t "LINCOLNABRAHAM" ) 

returns a zero. For a slightly different use of instr, look at 

INSTR (3* "1232123" * "12") 

which returns 5. 

Sample Program 

This program gets search and target text from the keyboard, then locates all 
occurrences of the target text in the search text. Line 90 is just for "show." 

10 CLEAR 1000 

20 CLS 

30 INPUT "SEARCH TEXT"? S$ 

413 INPUT "TARGET TEXT'S T* 

45 CLS 

50 C = s P = 1 'P = POSITION* C = COUNT 

60 F = INSTR<PfS*fTt) 

70 IF F = THEN 120 

80 C = C + 1 

90 PRINT @0>LEFT$(S$*F-i> + STRING* ( LEN(T$ )> 191 ) + 

- RIGHT* <S*>LEN<S*)-F-LEN(T*)+1> 
100 P = F + LEN(T$) 

110 IF P <= LEN(S$) - LEN(T$) + 1 THEN S0 
120 PRINT "FOUND "5 C5 "OCCURRENCES" 
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LINE INPUT 

Input a Line from Keyboard 



prompt is a prompting message. 

variable is the name that will be assigned to the line you type in. 



line input (or LiNEiNPUT—the space is optional) is similar to input, except: 

• The Computer will not display a question mark when waiting for your 
operator's input. 

• Each line input statement can assign a value to just one variable. 

• Commas and quotes your operator can use as part of the string input. 

• Leading blanks are not ignored — they become part of variable. 

• The only way to terminate the string input is to press (ENTER). 

line input is a convenient way to input string data without having to worry 
abou t accid ental entry of delimiters (commas, quotation marks, colons, etc.). 
The CENTER) key serves as the only delimiter. If you want anyone to be able to 
input information into your program without special instructions, use the line 
input statement. 

Some situations require that you input commas, quotes and leading blanks as 
part of the data, line input serves well in such cases. 

Examples 

LINE INPUT A$ 

Input a$ without displaying any prompt. 

LINE INPUT "LAST NAME , FIRST NAME? H 5N$ 

Displays a prompt message and inputs data. Commas will not terminate the 
input string, as they would in an input statement. 

Sample Program 

200 REM CUSTOMER SURVEY 
205 CLEAR 1000 
207 PRINT 



110 



DISK BASIC 



210 LINE INPUT "TYPE IN YOUR NAME "5 A$ 

220 LINE INPUT "DO YOU LIKE YOUR COMPUTER? "5 B$ 

230 LINE INPUT "WHY? " 5 C$ 

235 PRINT 

240 PRINT A$ : PRINT 

250 IF B$= "NO" THEN 270 

2S0 PRINT "I LIKE MY COMPUTER BECAUSE "5 C$ :END 

270 PRINT "I DO NOT LIKE MY COMPUTER BECAUSE "5 C$ 

Notice that when line 210 is executed, a question mark is not displayed after the 
statement, "Type in your name." Also, notice on line 230 you can answer the 
question "Why" with a statement full of delimiters, commas and quotes. 




MID$ = 

Replace Portion of String 



wd$ (oldstring, position, length) = replacement-string 

o/tf5fr/7?ff is the variabie-name of the string you want to change. 

pessiei 
character to be changed. 

length is a numeric expression specifying the number of characters to be 
replaced. 

replacement-string is a string expression to replace the specified portion 
of oldstring. 

Note: if replacement-string is shorter than length, then the entire replacement- 
string 



This statement lets you replace any part of a string with a specified new string, 
giving you a powerful string editing capability. 

Note that the length of the resultant string is always the same as the original 

string. 

Examples 

a$ = "Lincoln" in the examples below: 
MID$(A$, 3* 4) = "12345": PRINT A$ 
which returns LH234N. 
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MID$(A$* 1 * 2) = "": PRINT A* 

which returns Lincoln. 

MID$(A$> 5) = "123*15"; PRINT A$ 

returns LINC123. 

MID$(A$* 5) = "01": PRINT A$ 

returns lincoin. 

MID$(A$* 1*3)= "***": PRINT A$ 

returns ***coln. 



Sample Program 



770 CLS: PRINT: PRINT 

780 LINE INPUT "TYPE IN A MONTH AND DAY HM/DD* "3 B$ 

790 P = INSTR(S$* "/") 

800 IF P = THEN 7B0 

810 MID*(S$t Pt 1) = CHR*U5) 

8Z0 PRINT S$ " IS EASIER TO READ* ISN'T IT?" 

This program uses instr to search for the slash ("/"). When it finds it 
(if it finds it), it uses MiD$ = to substitute a " - " (Chr$(45)) for it. 



NAME 

Renumber the Current Program 



newWrn? specifies the new line number of the first line to be renumbered, 

stertttne specifies the line number in the original program where 
renumbering will start. If omitted, the entire program will be 

increment specifies the increment to be used between each successive line 
number, if omitted, 10 is used. 
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Examples 

NAME 

Renumbers the entire program: 10, 20, 30, . . . 

NAME 8000*5000*100 

Renumbers all lines numbered from 5000 up; the first renumbered line will 
become 6000, and the following lines will be incremented by 100. All line 
references within your program will be renumbered also. 

USRn 

Call to User's External Subroutine 




usR/f (nmexp) 



wtt#m irsjieeille^ qiie of ten available usr calls, /?=B,1,2,^,9. If /» is 
p^jttetf, zero is assumed. 

fim&M an integerlrom -32768 to 32767 and Is passed as an integer 
argument to the routine. 



These functions (usro through USR9) transfer control to machine-language 
routines previously defined with DEFUSRn statements. 

When a urs call is encountered in a statement, control goes to the address 
specified in the defusraz statement. This address specifies the entry point to your 
machine-language routine. 

Note: If you call a usrh routine before defining the routine entry point with 
DEFUSRrc, an illegal function call error will occur. 

You can pass one argument and retrieve one output value directly via the usr 
argument; or you can pass and retrieve arguments indirectly via poke and peek 
statements. 

Example 

1.0 DEFUSR1=&H7D00 

20 REM, ♦♦MORE PROGRAM LINES HERE 

100 A=USR1<X) 

The effect of this sequence is to: 
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1 . Define usr as a routine with an entry point at hex 7D00 (line 10). 

2. Transfer control to the routine; the value x can be passed to the routine if the 
routine makes the call described below (line 100). 

3. When the routine returns to basic, the variable a may contain the value 
passed back from the routine (if your routine makes the jump described 
below); otherwise a will be assigned the value of x (line 100). 

Passing arguments to and from USR routines 

There are several ways to pass arguments back and forth between your basic 
main program and your usr routines: the two major ways are listed below. 

1. poke the argument(s) into fixed ram locations. The machine-language routine 
can then access these values and place results in other ram locations. When 
the routine returns control to basic, your program can peek into these 
addresses to pick up the "output" values. This is the only way to pass two 
or more arguments back and forth. 

2. Pass one argument to the routine as the argument in the usRn call, then use 
special rom calls to access this argument and return a value to basic. This 
method is limited to sending one argument and returning one value (both 
are integers). 

rom Calls 



call 0A7FH Puts the usr argument into the hl register pair; h contains msb, l 
contains lsb. This call should be the first instruction in your usr 
routine. 

jp oa9ah Use this jump to return to basic; the integer in hl becomes the 
output of the usr call. If you don't care about returning hl, then 
execute a simple RETurn instruction instead of this jump. 

Listed below is an assembled program to white out the display (an "inverse" 
clear key!). Don't type it in. Type in the basic program that follows it. 



7D00 



3C00 
00BF 
03FF 



00100 
00110 
00120 
00130 
00140 
00150 
00160 
00170 
00180 
00130 
00200 
00210 
00220 



ZAP OUT SCREEN USR FUNCTION 



ORG 



EQUATES 

MI DEO 
WHITE 
COUNT 



EQU 
EQU 
EQU 



7D00H 



3C00H 

0BFH 

3FFH 



5 start of mi deo ram 
;all white graphics byte 

i NUMBER OF BYTES TO HOME 



PROGRAM CHAIN MOVES X'BF' INTO ALL OF VIDEO RAM 
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7D00 21003C 
7D03 3GBF 
7D05 11013C 
7D08 01FF03 
7D0B EDB0 

7D0D C3 
7D00 



0(3230 ZAP 

00240 

00250 

002G0 

00270 

00280 5 

00290 

00300 



LD 
LD 
LD 
LD 
LDIR 

RET 
END 



HLtVIDEO 
(HL) , WHITE 
DEtVIDEO+1 
BC»C0UNT 



?AP 



5SOURCE ADDRESS 
iPUT OUT 1ST BYTE 
^DESTINATION ADDRESS 
5NUMBER OF ITERATIONS 
5DO IT TO IT! ! ! 

iRETURN TO BASIC 



This routine can be pokec! into ram and accessed as a usr routine. First start basic and answer the 
MEMORY SIZE question with 31999. Then run the program. 

100 ' PROGRAM: USR1 

110 ' EXAMPLE OF A USER MACHINE LANGUAGE FUNCTION 

115 ' DEPRESS THE '(§' KEY WHILE NUMBERS ARE PRINTING TO STOP 

120 ' 

130 / ******* POKE MACHINE PROGRAM INTO MEMORY ******* 

140 ' 

150 DEFUSR1 = &H7D00 

1S0 FOR X = 32000 TO 32013 '7D00 HEX EQUAL 32000 DECIMAL 

170 READ A 

180 POKE X* A 

190 NEXT X 

192 ' 

194 ' ******* CLEAR SCREEN & PRINT NUMBERS 1 THRU 100 ******* 

195 ' 
200 CLS 

205 PRINT TAB* 15)5 "WHITE-OUT USER ROUTINE": PRINT 

210 FOR X = I TO 100 

220 PRINT X5 

225 A$ = IIMKEY*: IF A$ = "@" THEN END 

230 NEXT X 

240 ' 

250 ' ******* JUMP TO WHITE-OUT SUBROUTINE ******* 

2S0 ' 

270 X = USR1 (0) 

280 FOR X - 1 TO 1000: NEXT X 'DELAY LOOP 

290 GOTO 200 

300 ' 

310 ' ******* DATA IS DECIMAL CODE FOR HEX PROGRAM ******* 

320 ' 

330 DATA 33>0>6B*54»19i # 17 1 1 *G0>1 *255 t3 *237 » 17G ,201 

Run the program. An equivalent basic white out routine takes a long time by comparison! 
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Disk-Related Features 

Disk basic provides a powerful set of commands, statements and functions 
relating to disk i/o under trsdos. These fall into two categories: 

1 . File manipulation: dealing with files as units, rather than with the distinct 
records the files contain. 

2. File access: preparing data files for i/o; reading and writing to the files. 

Under the heading, File Manipulation, we will discuss the following 
commands. 

kill Delete a program or data file from the disk 

load Load a basic program from disk 

merge Merge an ASCII-format basic program on disk with one 

currently in ram 
run "pro gram" Load and execute a basic program stored on disk 

save Save the resident basic program on disk 

Under the heading, File Access, we will discuss the following statements and 
functions. 



Statements 

OPEN 

CLOSE 

INPUT # 

LINE INPUT# 

PRINT# 

HELD 

GET 

PUT 

LSET 

RSET 

Functions 

CVD 

CVI 
CVS 

EOF 
LOC 



Open a file for access (create the file if necessary) 

Close access to the file 

Read from disk, sequential mode 

Read a line of data, sequential mode 

Write to disk, sequential mode 

Assign field sizes and names to random-access file buffer 

Read from disk, random access mode 

Write to disk, random access mode 

Place value in specified buffer field, add blanks on the 

right to fill field 
Place value in specified buffer field, add blanks on the left 

to fill field 

Restore double-precision number to numeric form after 
GETting from disk 

Restore integer to numeric form after GETting from disk 

Restore single-precision number to numeric form after 
GETting from disk 

Check to see if end of file encountered during read 

get current record number. 
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LOF 
MKD$ 

MKI$ 
MKS$ 



Return number of last record in file 

Convert double-precision number to string so it can be put 

on disk 
Convert integer to string so it can be put on disk 
Convert single-precision number to string so it can be put 

on disk 
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File Manipulation 

KILL 

Delete a File from the Disk 



/j$$'4eM a file specification for an existing file, 



This command works like the trsdos kill command — see trsdos Library 
Commands. 



Example 

KILL H OLDFILE/BAS*PSWi H 

deletes the file specified from the first drive which contains it. 

Do not kill an open file, or you may destroy the contents of the diskette. (First, 
close the open file.) 

LOAD 

Load BASIC Program File from Disk 



where $jp$ defines a filespec for a basic program file stored on disk. 
r tells basic to nm the program after it is loaded. 



This command loads a basic program file into ram; if the r option is used, 
basic will proceed to run the program automatically; otherwise, basic will 
return to the command mode. 
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load without the R option clears all variables and closes all open files, load 
with the R option clears all variables but does not close the open files. 

load with the r option is equivalent to the command run exp$,R. Either of 
these commands can be used inside programs to allow program chaining — one 
program calling another, etc. 

Example 

L0AD M PR0G1/BAS:2 M 

Clears resident basic program and loads progi/bas from Drive 2; returns to 
basic command mode. 



MERGE 

Merge Disk Program with Resident Program 



MERGE i 




&$$ if 1W ^gelfication for an Ascii-format basic disk file, eg., a program 



merge is similar to load — except that the resident program is not erased before 
the new program exp$ is loaded. Instead, the new program is merged into the 
resident program. 

That is, program lines in exp$ will simply be inserted into the resident program 
in sequential order. If line numbers in exp$ coincide with line numbers in the 
resident program, the resident lines will be replaced by those from exp$. 
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Program on Disk 



Program in Ram 



10 


+ 


10 




20 


30 


40 


50 


60 


70 


90 


90 


100 




110 




120 





Merged Program in Ram 



10 



20 



30 



40 



50 



60 



70 



90 



100 



110 



120 



Sample Use 

Save this program in ascii format. 



1000 REM ♦ , ♦ SUBROUTINE TO SAY HELLO 
1010 PRINT "HELLO! " 
1020 RETURN 

Type NEW (ENTER) , then type in this program. 

100 CLS 

110 PRINT "LET'S CALL THE SUBROUTINE ♦ ♦ , 

120 PRINT "DIALING NOW . ♦ , " 

130 FOR 1=1 TO 1000 : NEXT 

140 GOSUB 1000 

150 PRINT "BACK FROM SUBROUTINE." 

1S0 END 



Now type MERGE "file" using the file name given to the first file. List the program. Then run it. 

RUN"program" 

Load and Execute a Program from Disk 



mHfii^M 



/^^ is llie name of a basic prograiii file. It is a string expression. (Iff a string 
constant is used, it must be enclosed in quotes.) The ,r option causes 
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This command loads and executes a basic program stored on disk. It may be 
used inside a program to allow chaining (one program calling another). 

Examples 

RUN "PROG" 

Loads and executes prog (all open files are closed first). 

A$="NEWPR0G n 
RUN A*t R 

Loads and executes newprog (all open files remain open). 




SAVE 

Save Program onto Disk 






This command lets you save your basic programs on disk. You can save the 
program in compressed or ascii format. 

Using compressed format takes up less disk space and is faster during both 
saves and loads. Using the ascii option makes it possible to do certain things 
that cannot be done with compressed format basic files. 

For example: 

• The merge command requires that the disk file be in ascii form. 

• Programs which read in other programs as data will typically require that the 
data programs be stored in ascii. 

• The trsdos command append also requires that disk files be in ascii form. 
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Examples 

SAVE"FILEi/BAS* J0HN0D0E:3" 

saves the resident basic program in compressed format with the file name filei, 
extension /bas, password .johnqdoe; the file is placed on Drive :3. 

SAUE"MATHPAK/TXT n *A 

saves the resident program in ascii form, using the name mathpak/txt, on the 
first nonwrite-protected diskette. 

Upon completion of a save, basic returns in the command mode. 
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File Access 

This section is divided into four parts: 

1. Creating files and assigning buffers — open and close 

2. Statements and functions 

3. Sequential i/o techniques 

4. Random i/o techniques 

If this is your first experience with disk file access, you should concentrate on 
parts 1 , 3 and 4, perhaps just skimming through part 2 to get a general idea of 
how the functions and statements work. Later you can go back to part 2 and 
learn the details of statement and function syntax. 

Creating Files and Assigning Buffers 

During the initialization dialog, you type in a number in response to how many 
files? The number you type in tells basic how many buffers to create to handle 
your disk accesses (reads and writes). 

Each buffer is given a number from 1 to 15. If you type: 



HON MANY FILES? 3V (ENTER) 

basic sets aside 3 buffers, numbered 1,2,3. 

You can think of a buffer as a waiting area that data must pass through on the 
way to and from the disk file. When you want to access a particular file, you 
must tell basic which buffer to use in accessing that file. You must also tell 
basic what kind of access you want — sequential output, sequential input, or 
random input/output. 

All this is done with the open statement, and "undone" with the close 
statement. 



OPEN 
Open a File 



it will be created. 
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o Sequential output starting at the first record. If the file is not 
found, It will be created. 

e (Extend) Sequential output starting at end of file. If the file is not 
found. It will be created. 

r Random input/output, if the file is not found, it will be cmatedf 

If mode is a constant, it must be enclosed in quotes. 

buffer is a numeric expression specifying which buffer is to be used; 

fffeis a string expression containing the file specification. If a constant is 
used, it must be enclosed in quotes. 

record-length is a numeric expression from to 256 specifying the logical 
record length. is the same as 256. This option may only be used if 
¥ariable-length records were requested during initialization (How 
Many Files?). If record-length is omitted, 256 is used, record-length 
is used with Random access only. 



This statement lets you create a file, write data into it, update it, and read it. For 
details on file access, see Methods of Access later in this section. 

If file includes a drive specification, basic will use only the specified drive. If 
no drive is specified, basic will search for a matching file, starting with the 
master drive (usually Drive 0). 

Examples 

OPEN "0" * 1 t "DATAFILE" 

Opens datafile (creates it if it doesn't already exist) for sequential output. 
Output will be done through buffer #1. Records will be 256 bytes long. Since 
the "o" mode is specified, output will start at the first record in the file. 
If "e" is used instead of "o", output will start at the end of the file. 

OPEN "R", 2* H PAYROLL/A :1" , G4 

Opens/creates payroll/a for random input/output. Access will be through 
buffer #2. Records will be 64 bytes long (if basic was initialized for variable- 
length records). 

BUFFER = 3: FILE$ = "DATA": RECLN = 128 
OPEN "R", BUFFER* FILE** RECLN 

Opens/creates data for random input/output. Access will be through buffer #3. 
Records will be 128 bytes long (if basic was initialized for variable-length 
records). 
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CLOSE 

Close Access to the File 



nmexp has a value from 1 to 15, and refers to the f He's buffer number 
lle^ 



This command terminates access to a file through the specified buffer(s). 
If nmexp has not been assigned in a previous open statement, then 

close nmexp 

has no effect. 

Examples 

CLOSE 1 #2 t8 

Terminates the file assignments to buffers 1 , 2 and 8. These buffers can now be 
assigned to other files with open statements. 

CLOSE FIRSTX+COUNTX 

Terminates the file assignment to the buffer specified by the sum 
(first% + COUNT%). 

Do not remove a diskette which contains a file opened for writing (mode = O, 
E, or R). First close the file. This is because the last 256 bytes of data may not 
have been written to disk yet. Closing the file will write the data, if it hasn't 
already been written. 

Any modification to the resident program (new, editing, load, merge, etc.) 
will cause open files to be closed. 
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INPUT# 

Sequential Read from Disk 



where nmexp specifies a sequential input file buffer, /?mexp=1,2,..,15. 
var is the variable name to contain the data from the file. 



This statement inputs data from a disk file. The data is input sequentially. That 
is, when the file is first opened, a pointer is set to the beginning of the file. 
Each time data is input, the pointer advances. To start over reading from the 
beginning of the file, you must close the file and re-open it. 

input# doesn't care how the data was placed on the disk — whether a single 
print# statement put it there, or whether it required 10 different print# 
statements. What matters to input# are the positions of the terminating 
characters and the eof marker. 

To input# data successfully from disk, you need to know ahead of time what 
the format of the data is. Here is a description of how input# interprets the 
various characters it encounters when reading data. 

When inputting data into a variable, basic ignores leading blanks; when the 
first non-blank character is encountered, basic assumes it has encountered the 
beginning of the data item. 

The data item ends when a terminating character is encountered or when a 
terminating condition occurs. The particular terminating characters vary, 
depending on whether basic is inputting to a numeric or string variable. 

Special Note 

Here's an important exception to keep in mind in reading the following material. 

When (ENTER) (a carriage return) is preceded by © (a line feed), the CENTER) is 
not taken as a terminator. Instead, it becomes a part of the data item (string 
variable) or is simply ignored (numeric variable). 

(To enter the £) ch aracter from the keyboard, press the down-arrow character. 
To enter the (ENTER) character, press (INTER) .) 

This exception applies to all cases noted below where (ENTER) is said to be a 
terminator. 
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'^s«*^^ 



Numeric Input 

Suppose the data image on disk is 

1*234 -33 27 [ENTER) 

(ENTER) denotes a carriage-return character (ascii code decimal 13). 

Then the statement 

INPUT#1 * A>B,C 

or the sequence of statements 

INPUT#1*A: INPUT#ltB: INPUT#1 »C 

will assign the values as follows: 

A- 1.234 
B- -33 

C = 27 

This works because blanks and (ENTER) serve as terminators for input to numeric 
variables. The blank before 1.234 is a ' 'leading blank," therefore it is ignored. 
The blank after 1.234 is a terminator; therefore basic starts inputting the second 
variable at the - character, inputs the number -33, and takes the next two 
blanks as terminators. The third input begins at the 2 and ends with the 7. 

String Input 

When reading data into a string variable, input ignores all leading blanks; 
the first non-blank character is taken as the beginning of the data item. 

If this first character is a double-quote ("), then input will evaluate the data as 
a quoted string: it will read in all subsequent characters up to the next double- 
quote. Commas, blanks, and (ENTER) characters will be included in the string. 
The quotes themselves do not become a part of the string. 

If the first character of the string item is not a double-quote, then input will 
evaluate the data as an unquoted string: it will read in all subsequent characters 
up to the first comma, or (ENTER) . If double-quotes are encountered, they will be 
included in the string. 

For example, if the data on disk is: 

PECOS, TEXAS' 'GOOD MELONS" 

Then the statement 

INPUTal t A$>B$»C$ 
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would assign values as follows: 

A$ = PECOS 

B$= TEXAS "GOOD MELONS" 

C$ = null string 

If a comma is inserted in the data image before the first double quote, c$ will 
get the value, good melons. 

These are very simple examples just to give you an idea of how input works. 
However, there are many other ways to input data — different terminators, 
different target variable types, etc. 

Rather than taking a shotgun approach and trying to cover them all, we'll give a 
generalized description of how input works and what the terminating characters 
and conditions are, and then provide several examples. 

When basic encounters a terminating character, it scans ahead to see how many 
more terminating characters it can include with the first terminator. This ensures 
that basic will begin looking for the next data item at the correct place. 

The list below defines the various terminating sets input# will look for. It will 
always try to take-in the largest set possible. 

Numeric-input terminator sets 

end of file encountered 

255th data character encountered 

, (comma) 

(ENTER) 

CENTER) © 

[ ...][ (ENTER) ] 

[ . . .HCHUH)©] 

Quoted-string terminator sets 

end of file encountered 

255th data character encountered 

" (double quote) 

"[ ...][,] 

" t • ..][ (ENTER)] 

"[ ...HGHUH)©] 

Unquoted-string terminator sets 

end of file encountered 

255th data character encountered 

'canst©] 

Figure 13 describes how input# assigns data to a variable. 
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EXAMINE NEXT 
CHARACTER 



T 








\/ 








NO 




PUT IT INTO 
TEMPORARY 
SAVE AREA 


-s. 


EXAMINE NEXT 
CHARACTER 


y/lS I 




^ 


S 





PICKUP THE 

TERMINATOR 

SET 



GET DATA FROM 
TEMPORARY 
SAVE AREA 



EVALUATE IT 



ASStGN TO 
VARIABLE 



Figure 13. Input process. 

The following table shows how various data images will be read-in by the 
statement: 

INPUT*! tAtBtC 



Ex.# 



Image on disk 



123,45 (ENTERS 8,2E4 70B8 [ENTER) 



3©(HT|H) 4 fENTER) 5 (ENTER) AlZeof 



1 ,,2,3*4 CENTER) 



i ,3 t eof 



Values 
assigned 



A- 123.45 
B = 82000 
C = 7000 



A = 34 
B = 5 
C = 



A=1 
B = 
C = 2 



A=1 

B = 3 

C = eof error 



(eof = end of file): 

In Example 2 above, why does variable c get the value 0? When the input 
reaches the end of file, it terminates that last data item, which then contains 
4t Ai2." This is evaluated by a routine just like the basic val function — which 
returns a zero since the first character of "a 12" is a non-numeric. 
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In Example 3, when input# goes looking for the second data item, it 
immediately encounters a terminator (the comma); therefore, variable B is given 
the value zero. 

The following table shows how various data images on disk will be read by the 
statement: 

IIMPUT#i ,A$>B$ 



Ex.# 


Image on disk 


Values assigned 


1 


"ROBERTS »J. "ROBERTS, M.N eof 


A$:ROBERTS,J. 
B$:ROBERTS,M.N. 


2 


ROBERTS, J., ROBERTS, M.N. (ENTER) 


A$:ROBERTS 
B$:J. 


3 


THE WORD "QUO" ,12345.789 (ENTER) 


A$:THE WORD "QUO" 
B$:1 2345.789 


4 


BYTElsJ (ENTER) UNIT OF MEMORY eof 


A$:BY I h(*J(ENTER) 
UNIT OF MEMORY 
B$:null (eof error) 



In Example 3, the first data item is an unquoted string, therefore, the double- 
quotes are not terminators, and become part of a$. 

In Example 4, the (ENTER) is preced ed by an ©, therefore it does not terminate 
the first string; both © and (ENTER] are included in a$. 



LINE INPUT# 

Read a Line of Text from Disk 



line mm#timxft, vart 

where nmexp specifies a sequential output file buffer, /miarp=1,2,...,15, 
^ the string data. 



Similar to line input from keyboard, this statement reads a "line" of string 
data into var$. This is useful when you want to read an Ascn-format basic 
program file as data, or when you want to read in data without following the 
usual restrictions regarding leading characters and terminators. 
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line input (or lineinput — the space is optional) reads everything from the first 
character up to: 

1 . an (ENTER) character which is not preceded by © 

2. the end of file 

3. the 255th data character (this 255 character is included in the string) 

Other characters encountered — quotes, commas, leading blanks, © ( ENTER ) 
pairs — are included in the string. 

For example, if the data looks like: 




10 CLEAR 500 (ENTER) 

20 OPEN"!" fl »"PR0G" (ENTER) 



then the statement 
LIIMEINPUT#1 »A$ 
could be used repetitively to read each program line, one line at a time. 

PRINT# 

Sequential Write to Disk File 



; '/ii^:^^;ii|li^oKlb be evaluated and written to disk. 



This statement writes data sequentially to the specified file. When you first open 
a file for sequential output, a pointer is set to the beginning of the file, therefore 
your first print# places data at the beginning of the file. At the end of each 
print# operation, the pointer advances, so the values are written in sequence. 
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A print# statement creates a disk image similar to what a print to display 
creates on the screen. Remember this, and you'll be able to set up your print# 
list correctly for access by one or more input statements. 

print# does not compress the data before writing it to disk; it writes an ascii- 
coded image of the data. 

For example, if a — 123.45 

PRINT*1 >A 

will write a nine-byte character sequence onto disk: 



123,a5 CENTER! 

The punctuation in the print list is very important. Unquoted commas and semi- 
colons have the same effect as they do in regular print to display statements. 

For example, if a = 2300 and b = 1.303, then 

PRINT#1 >A>B 

places the data on disk as 



2300 1,303 [ENTER) 

The comma between a and b in the print# list causes 10 extra spaces in the 
disk file. Generally you wouldn't want to use up disk space this way, so you 
should use semi-colons instead of commas. 

PRINT#1 *A5B 

writes the data as: 



2300 1,303 CENTER] 

print# with numeric data is quite straightforward — just remember to separate 
the items with semi-colons. 

print# with string data requires more care, primarily because you have to insert 
delimiters so the data can be read back correctly. In particular, you must 
separate string items with explicit delimiters if you want to input# them as 
distinct strings. 

For example, suppose: 

A$="J0HN Q. DOE" and B*= " 100-01 -001 " 

Then: 

PRINT*! * A$?B$ 

would produce this image on disk: 



JOHN Q* DOE100-0I-001 [ENTER] 

which could not be input back into two variables. 

The statement: 
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PRINT*! t a$; h *" ;b$ 

would produce: 

JOHN Q. DOE* 100-01-001 

which could be input# back into two variables. 

This method is adequate if the string data contains no delimiters — commas or 
(ENTER) — characters. But if the data does contain delimiters or leading blanks 
that you don't want to ignore, then you must supply explicit quotes to be written 
along with the data. For example, suppose A* = H DOE* JOHN Q t !I andB$ = "100 
-01-001" 




If you use 

PRINT*! *A*i" >" ?B$ 

the disk image will be: 



DOE* JOHN 0* *100-01-00i (ENTER) 

When you try to input this with a statement like 

INPUT#2*A$*B$ 

a$ will get the value doe, and b$ will get john q. — because of the comma after 
doe in the disk image. 

To write this data so that it can be input correctly, you must use the chr$ 
function to insert explicit double quotes into the disk image. Since 34 is the 
decimal ascii code for double quotes, use chr$(34) as follows: 

PRINT#1 *CHR$(34> 5A$SCHR*<34) iB$ 

this produces the disk image 



"DOE* JOHN Q, "100-01-001 CENTER] 
which can be read with a simple 

INPUT*2*A$B$ 

Note: You can also use the chr$ function to insert other delimiters and control 
codes into the file, for example: 

chr$(10) © Line Feed 

chr$(13) carriage return ( (ENTER) character) 

chr$(H) or chr$(I2) line-printer top-of-form 

USING Option 

This option makes it easy to write files in a carefully controlled format. 
For example, suppose: 

A$= n LUDWIG if 
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B$="VAN" 

C*= "BEETHOVEN" 

Then the statement 

PRINT»1 tUSING"! , !, I Z" iA*!B*;C* 
would write the data in nickname form: 

L.V.BEET (ENTER)- 

(In this case, we didn't want to add any explicit delimiters.) See the print using 
description in the level ii basic Reference Manual for a complete explanation of 
the field-specifiers. 

Random Access Statements 

FIELD 

Organize a Random File-Buffer into Fields 



mionmexp,nmexpnsvar1$l,nmexp2nsvar2$...\ 

nmexp specifies a random access file buffer, nmexp= 1 ,2,. ..,15. 

nmexpl specifies the length of the first field . 

vart$ defines a variable name for the first field. 

nmexp2 specifies the length of the second field. 

uar2$ defines a variable name for the second field. 

... Subsequent nmexp as var$ pairs define other fields in the buffer. 

Note: The sum of all the field-lengths must not exceed the record length, and 
should equal the record length. 



Before FiELDing a buffer, you must use an open statement to assign that buffer 
to a particular disk file (you must use random access mode). Then use the field 
statement to organize a random file buffer so that you can pass data from basic 
to disk storage and vice- versa. 

Each random file buffer has up to 256 bytes which can store data for transfer 
from disk storage to basic or from basic to disk. (When variable-length files are 
used, maximum may be from 1 to 256.) However, you need a way to access this 
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buffer from basic so that you can either read the data it contains or place new 
data in it. The field statement provides the means of access. 

You may use the held statement any number of times to "re-organize" a file 
buffer. FiELDing a buffer does not clear the contents of the buffer; only the 
means of accessing the buffer (the field names) are changed. Furthermore, two 
or more field names can reference the same area of the buffer. 

Examples 

FIELD 1 f 128 AS A$ , 128 AS B$ 

This statement tells basic to assign the first 128 bytes of the buffer to the string 
variable a$ and the remaining 128 bytes to b$. If you now print a$ and b$, you 
will see the contents of the buffer. Of course, this value would be meaningless 
unless you have used get to read a 256-byte record from disk. 

Note: All data — both strings and numbers — must be placed into the buffer in 
string form. There are three pairs of functions (mki$/cvi,mks$/cvs,mkd$/cvd) 
for converting numbers to strings and vice- versa. See "Functions" below. 

FIELD 3» IS AS NM$ > 25 AS AD$ , 10 AS CY* » 2 AS ST$ H AS ZP$ 

The first 16 bytes of buffer 3 are assigned the buffer name nm$; the next 25, 
ad$; the next 10, cy$; the next 2, st$ and the next 7, zp$. The remaining 196 
bytes of the buffer are not fielded at all. 

More on field names 

Field names, like nm$,ad$,cy$,st$, and zp$, are not string variables in the 
ordinary sense. They do not consume the string space available to basic. 

Instead, they point to the buffer field which you assigned with the field 
statement. That's why you can use: 

100 FIELD 1 ,255 AS A$ 

without worrying about whether 255 bytes of string space are available for a$. 

If you use a buffer field name on the left side of an ordinary assignment 
statement, that name will no longer point to the buffer field; therefore, you 
won't be able to access that field using the previous field name. 

For example, 

A$ = B$ 

nullifies the effect of the field statement above (line 100). 

During random input, the get statement places data into the 255-byte buffer, 
where it can be accessed using the field names assigned to that buffer. During 
random output, lset and rset place data into the buffer, so you can then put 
the buffer contents into a disk file. 
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Often you'll want to use a dummy variable in a field statement to "pass 
over" a portion of the buffer and start fielding it somewhere in the middle. 
For example: 

FIELD It 1G AS CLIENT$(l)t 112 AS HIST*<1> 

FIELD it 128 AS DUMMY** 1G AS CLIENT$(2), 112 AS HIST$(2) 

In the second field statement, dummys serves to move the starting position of 
client$(2) to position 129. In this manner, two identical "subrecords" are 
defined on buffer number 1 . We won't actually use dummy$ to place data into 
the buffer or retrieve it from the buffer. 

The buffer now looks like this: 



16 


112 


16 


112 



CL$ 

d) 



HIST$ 

(D 



CL$ 

(2) 



HIST$ 

(2) 



DUMMY$ 



GET 

Read a Record from Disk- 



Random Access 



get mexpti;!imxp2i 

' into^ 15. 

nmexp2 specifies which record to get in the lite; if omitted, the current 
record will be read. 



This statement gets a data record from a disk file and places it in the specified 
buffer. Before GETting data from a file, you must open the file and assign a 
buffer to it. That is, a statement like: 

open u R" ,nmexpl filespec 

is required before the statement: 

get nmexpl y nmexp2 

get tells basic to read record nmexp2 from the file and place it into the nmexpl 
buffer. If you omit the record number in get, basic will read the current record. 
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The "current record" is the record whose number is one higher than that of the 
last record accessed. The first time you access a file via a particular buffer, the 
current record is set equal to 1 . 



For example: 
Program statement 



Effect 



1000OPEN"R , \l, t 'NAME/BAS' 

1010 FIELD 1,... 

1020 GET 1 

1025 REM. ..ACCESS BUFFER 
1030 GET 1,30 

1035 REM... ACCESS BUFFER 
1040 GET 1,25 

1046 REM... ACCESS BUFFER 
1050 GET 1 



Open name/bas for random access 
using buffer 1 

Structure buffer 

get record 1 into buffer 1 

get record 30 into buffer 1 

get record 25 into buffer 1 

get record 26 into buffer 1 



If you are using variable-length records (not fixed-length), an attempt to get 
past the end of file will produce an error. 

If you are using fixed-length records, the same attempt will return a null record 
and no error will occur. To prevent this from occurring, you can use the lof 
function to determine the number of the highest numbered record. 



PUT 

Write a Record to Disk — Random Access 



pmmmp1hnmxfi2l 

rt/ite^$peeiiles a random access file buffer, nmexp- 1 ^.;>ilv 

nmmp2^e$i&$ the record number in the ii\B, nmexp2\$$BmMyf)\} 
want to write. If nmexp2 is omitted, the current record number is 
assumed. 



This statement moves data from a file's buffer into a specified place in the file. 
Before PUTting data in a file, you must: 

1 . open the file, thereby assigning a buffer and defining the access mode (must 
be r); 
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2. field the buffer, so you can 

3. place data into the buffer with lset and rset statements. 
When basic encounters the statement: 

PUT nmexp,nmexp2 
it does the following: 

• Gets the information needed to access the disk file 

• Checks the access mode for this buffer (must be r) 

• Acquires more disk space for the file if necessary to accommodate the record 
indicated by nmexp2 

• Copies the buffer contents into the specified record of the disk file 

• Updates the current record number to equal nmexp2 + 1 

The "current record" is the record whose number is one higher than the last 
record accessed. The first time you access a file via a particular buffer, the 
current record is set equal to 1 . 

If the record number you put is higher than the end-of-file record number, then 
nmexpl becomes the new end-of-file record number. 

LSET and RSET 

Place Data in a Random Buffer Field 






These two statements let you place character-string data into fields previously 
set up by a field statement. 

For example, suppose nm$ and ad$ have been defined as field names for a 
random file buffer. nm$ has a length of 18 characters, and ad$ has a length of 
25 characters, 

Now we want to place the following information into the buffer fields so it can 
be written to disk: 
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name: JIM CRICKET* JR. 

address: 2000 EAST PECAN ST, 

This is accomplished with the two statements: 

LSET NM$="JIM CRICKET »JR, " 
LSET AD$="2000 EAST PECAN ST. " 

This puts the data in the buffer as follows: 



JIM CRICKET. JR. 



Z000 EAST PECAN ST. 



NM$ 



AD$ 



Note that filler spaces were placed to the right of the data strings in both cases. 
If we had used rset instead of lset statements, the filler spaces would have 
been placed on the left. This is the only difference between lset and rset. 

For example: 

RSET NM*="JIM CRICKET. JR. " 
RSET AD$="2000 EAST PECAN ST. " 

places data in the fields as follows: 



JIM CRICKET. JR. 



2000 EAST PECAN ST, 



NM$ 



AD$ 



If a string item is too large to fit in the specified buffer field, it is always 
truncated on the right. That is, the extra characters on the right are ignored. 

CVD, CVI and CVS 

Restore String to Numeric Form 



vrnfexi 



iiititi 



exp$ defines an eight-character string; exp$ is typically the name of a 
buffer field containing a numeric string. If im(exp$)<S, an illegal 
function call error occurs; if im(exp$)>&, only the first eight 




„ a two-character string; exp$ is typically the name of a buffer 
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ais(exp$} 



a ft)iH>characfer string; exp$ is typically the name of a buffer 
lieiii containing a numeric siring. If Lm(exp$)<4, aw illegal function 
call error occurs; if i£u(exp$}>4, only the first four characters are 



These functions let you restore data to numeric form after it is read from disk. 
Typically the data has been read by a get statement, and is stored in a random- 
access file buffer. 

The functions cvd, cvi, and cvs are inverses of mkd$, mki$, and mks$, 
respectively. 

For example, suppose the name grosspays references an eight-byte field in 
a random-access file buffer, and after GETting a record, grosspays contains a 
mkds representation of the number 13123.38. 

Then the statement: 

PRINT CUD(GROSSPAY$) -TAXES 

prints the result of the difference, 13 123.38 -taxes. Whereas the statement: 

PRINT GROSSPAY*-TAXES 

will produce a type mismatch error, since string values cannot be used in 
arithmetic expressions. 

Using the same example, the statement 

A*=CUD(GROSSPAY$) 

assigns the numeric value 13123.38 to the double-precision variable a#. 



EOF 

End-Of-File Detector 



nmexp specifies a file buffer, nmexp=1,2„..,tt. 
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This function checks to see whether all characters up to the end-of-file marker 
have been accessed, so you can avoid input past end errors during sequential 
input. 

Assuming nmexp specifies an open file, then EOF(nmexp) returns (false) when 
the eof record has not yet been read, and - 1 (true) when it has been read. 

Examples 

IF E0F(5) THEN PRINTEND OF FILE"FILENM* 
IF EOF(NM) THEN CLOSE NM'Z 

The following sequence of lines reads numeric data from data/txt into the 
array a( ). When the last data character in the file is read, the eof test in line 
30 "passes," so the program branches out of the disk access loop, preventing 
an input past end error from occurring. Also note that the variable i contains 
the number of elements input into array a( ). 

5 DIM A<100> 'ASSUMING THIS IS A SAFE VALUE 

10 OPEN "I" tl * "DATA/TXT" 

20 11=0 

30 IF E0F( I ) THEN 70 

40 INPUTtti tfi(IX) 

50 n.=n.+i 

S0 GOTO 30 

70 REM PROGRAM CONTINUES HERE AFTER DISK INPUT 



LOC 

Get Current Record Number 



file number is a numeric expression specifying the buffer for a currently- 
opiinrt^ 



loc is used to determine the current record number, i.e., the number of the last 
record read since the file was opened, loc is only valid after a get. 



Example 

PRINT LOC(l) 
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1310 At = "WILLIAM WILSON" 



1320 GET 1 



<+l 



1330 IF N$ = A$ THEN PRINT "FOUND IN RECORD" LOC(l): CLOSE- 

END 
1340 GOTO 1320 

This is a portion of a program. Elsewhere the file has been opened and fielded 
n$ is a field variable. If n$ matches a$ the record number in which it was found 
is printed. 



LOF 

Get End-Of-File Record Number 



lor(nmexp) 
nmexpsp 



'^mmim : mwmexfi= 1,2,.. ..is. 



This function tells you the number of the last, i.e., highest numbered, record 
in a file. It is useful for both sequential and random access. 

For example, during random access to a pre-existing file, you often need a 
way to know when you've read the last valid record, lof provides a way. 

lof is valid as soon as a previously created file is opened. If a file is extended 
lof is not valid until a get is executed. 

Examples: 

10 OPEN "R" ,1 ."UNKNOWN/TXT" 

20 FIELD 1 ,255 AS A$ 

30 F0RI%=1 TO L0F(1) 

40 GET 1 ,11 

50 PRINT A$ 

60 NEXT 

In line 30, lof(d specifies the highest record number to be accessed. 

Note: If you attempt to get record numbers beyond the end-of-file record basic 
simply fills the buffer with hexadecimal zeros, and no error is generated. ' 
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When you want to add to the end of a file, lof tells you where to start adding: 

100 IX=L0F(1)+1 'HIGHEST EXISTING RECORD 
110 PUT 1 ill 'ADD NEXT RECORD 



MKD$, MKI$, and MKS$ 
Convert Data, Numeric-to-String 










These functions change a number to a "string." Actually the byte values which 
make up the number are not changed; only one byte, the internal data-type 
specifier, is changed, so that numeric data can be placed in a string variable. 

That is: 

mkd$ returns an eight-byte string. 
mki$ returns a two-byte string. 
mks$ returns a four-byte string. 



Examples 

LSET TALLY*=MKI*(IZ) 

Field name tally$ would now contain a two-byte representation of the 
integer i%. 

A*=MKIt(8/I) 
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AS becomes a two-byte representation of the integer portion of s/i Any 

^Z:\TTk T;f- ^ th3t A$ m thlS Case ic a normal ^ring 
vanable, not a buffer- field name. 

Suppose baseball/bat (a non-standard file extension) has been opened for 
random access using buffer 2, and the buffer has been FiELDed as follows 
field: 
length: 



NM$ 

16 



YRS$ 
2 



AVG$ 
4 



HR$ 

2 



AB$ 

4 



ERNINGS 

4 



nm$ is intended to hold a character string; avgs, ab$ and ernings, converted 
single-precision values; yrs$ and hr$, converted integers. 

Suppose we want to write the following data record: 

slow learner played 38 years; lifetime batting average 123- 
career homeruns, 11; at bats, 32768;... .earnings - 13.75. ' 
Then we'd use the make-string functions as follows: 

1000 LSET NM$="SL0W LEARNER" 
1010 LSET YRS$=MKI$(38) 
1020 LSET AVG*=MKS*(,123) 
1030 LSET HR$=MKI$(11) 
1040 LSET AB$=MKS$(32768) 
1050 LSET ERNING$=MKS*(-13.75) 

After this sequence, you can write slow learner's information to disk with 
he put statement. When you read it back from disk with get, you will need 
to restore the numeric data from string to numeric form, using cvi and cvs 
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Methods of Access 

Disk basic provides two means of file access: 

• Sequential — in which you start reading or writing data at the beginning of 
a file; subsequent reads or writes are done at following positions in the file. 

• Random — in which you start reading or writing at any record you specify. 
(Random access is also called direct access.) 

Sequential access is stream-oriented; that is, the number of characters read or 
written can vary, and is usually determined by delimiters in the data. Random 
access is record-oriented; that is, data is always read or written in fixed-length 
blocks called records. 

To do any input/output to a disk file, you must first open the file. When you 
open the file, you specify what kind of access you want: 

• o for sequential output 

• i for sequential input 

• r for random input/output 

• e (Extend) for sequential output starting at the end of file. 

You also assign a file buffer for basic to use during file accesses. This number 
can be from 1 to 15, but must not exceed the number of concurrent files you 
requested when you started basic from trsdos. For example, if you started 
basic with 3 files, you can use buffer numbers 1, 2, and 3. Once you assign a 
buffer number to a file, you cannot assign that number to another file until you 
Close the first file. 

Examples 

OPEN "0" t 1 * "TEST" 

Creates a sequential output file named test on the first available drive; if test 
already exists, its previous contents are lost. Buffer 1 will be used for this file. 

OPEN "I" t 2* "TEST 1 

Opens test for sequential input, using buffer 2. 

OPEN "R" t i * "TEST" 

Opens test for direct access, using buffer 1 . If test does not exist, it will be 
created on the first available drive. Since record length is not specified, 256-byte 
records will be used. 

OPEN "R" t 1 t "TEST" t 40 

Same as preceding example, but 40-byte records will be used. 

OPEN "E" f 1 * "TEST" 

Opens test sequentially for write and positions to EOF. 
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Sequential Access 



This is the simplest way to store data in and retrieve it from a file. It is ideal for 
storing free-form data without wasting space between data items. You read the 
items back in the same order in which they were written. 

There are several important points to keep in mind. 

1 . You must start writing at the beginning of the file. If the data you are seeking 
is somewhere inside, you have to read your way up to it. 

2. Each time you Open a file for sequential output, the file's previous contents 
are lost, unless you use "E" instead of "O" for the mode. 

3. To update (change) a sequential file, read in the file and write out the updated 
data to a new output file. 

4. Data written sequentially usually includes delimiters (markers) to signify 
where each data item begins and ends. To read a file sequentially, you must 
know ahead of time the format of the data. For example: Does the file consist 
of lines of text terminated with carriage returns? Does it consist of numbers 
separated by blank spaces? Does it consist of alternating text and numeric 
information? 

5. Sequential files are always written as Ascn-coded text, one byte for each 
character of data. For example, the number: 

1*2345 
requires 8 bytes of disk storage, including the leading and trailing blanks that 
are supplied. The text string: 

JOHNSON * ROBERT 

requires 15 bytes of disk storage. 

6. Sequential files are always written with a record length of 256. 

Sequential Output: An Example 

Suppose we want to store a table of English-to-metric conversion constants: 



English unit 


Metric equivalent 


1 inch 


2.54001 centimeters 


1 mile 


1.60935 kilometers 


1 acre 


4046.86 sq. meters 


1 cubic inch 


0.01638716 liter 


1 U.S. gaifon 


3.785 liters 


1 liquid quart 


0.9463 liter 


1 lb (avoir) 


0.45359 kilogram 
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First we decide what the data image is going to be. Let's say we want it to look 
like this: 

english unit ) metric unit, factor (ENTER) 

For example, the stored data would start out: 



IN->CMf 2*54001 CENTER) 

The following program will create such a data file. 

Note: X'OD' represents a carriage return. 

10 OPEN "0" tl t"METRIC/TXT" 

20 FOR 11=1 TO 7 

30 READ UNIT*, FACTR 

40 PRINTttl f UNIT$; " #" 3 FACTR 

50 NEXT 

G0 CLOSE 

70 DATA IN->CMf 2*54001 t MI->KM» 1*60935* ACRE->SQ * KM t 

404G.8S E-G 
80 DATA CU.IN->LTR> l*G3871GE-2t GAL->LTR , 3*785 
30 DATA LIQ*QT->LTR* 0*84G3» L6->KG> 0*45359 

Line 10 creates a disk file named metric/txt, and assigns buffer 1 for sequential 
output to that file. The extension /txt is used because sequential output always 
stores the data as Ascii-coded text. 

Note: If metric/txt already exists, line 10 will cause all its data to be lost. 
Here's why: Whenever a file is opened for sequential output, the end-of-file 
(eof) is set to the beginning of the file. In effect, trsdos "forgets" that 
anything has ever been written beyond this point. To avoid this, you could use e 
instead of o in line 10. 

Line 40 prints the current contents of units and factr to the file. Since the 
spring items do not contain delimiters, it is not necessary to print explicit quotes 
around them. The explicit comma is sufficient. 

Line 60 closes the file. The eof is at the end of the last data item, i.e., 0.45359, 
so that later, during input, basic will know when it has read all the data. 

Sequential Input: An Example 

The following program reads the data from metric/txt into two "parallel" 
arrays, then asks you to enter a conversion problem. 

5 CLEAR 500 

10 DIM UNIT*(9)t FACTRO) 'allows for up to 10 data pairs 

20 0PEN H r' tl ♦"METRIC/TXT" 

25 n, = 

30 IF EOF(l) THEN 70 

40 INPUT*! » UNIT$(II) tFACTR(IX) 
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50 IZ=IZ+1 

G0 G0T f 30 

70 CLOSE ' Conversion factors have been read-in 

100 CLS: PRINT TAB(5)"*** English to Hetric Conuersions ***" 

110 FOR ITEM'^B TO 12-1 

120 PRINT TAB(9) 5USING" (## ) 1 % « 5ITEMZ* 

UNIT$(ITEMI) 
130 NEXT 

140 PRINT @ 704* "Which conversion (0-B)" i 
150 INPUT CHOICER 

1G0 INPUT i! Er,ter English quantity" 5V 

170 PRINT"The Metric equivalent is" 0*FACTR(CH0ICE2) 
180 INPUT"Press (ENTER) to continue" 5X 
190 PRINT @ 704* CHRtOl) 'clear to end of frame 
200 GOTO 140 

Line 20 opens the file for sequential input. Input begins at the beginning of 
the file. 

Line 30 checks to see that the end-of-file record hasn't been reached. If it has, 
control branches from the disk input loop to the part of the program that uses ' 
the newly acquired data. 

Line 40 reads a value into the string array unit$( ), and a number into the 
single-precision array factr( ). Note that this input list parallels the print# list 
that created the data file (see the section "Sequential Output: An Example"). 
This parallelism is not required, however. We could just as successfully have 
used: 

40 INPUT*!* UNIT*<n,): INPUT#1 ,FACTR ( 11 ) 



How to update a file 

Suppose you want to add more entries into the English-Metric conversion file. 
You could simply re-Open the file with mode = e and print# the extra data. 
Or, you might want to leave the old file intact and output a new file: 

1 . Open the file for sequential input (Mode = i) 

2. Open another new data file for sequential output (Mode = o) 

3. Input a block of data and update the data as necessary 

4. Output the data to the new file 

5. Repeat steps 3 and 4 until all data has been read, updated, and output to the 
new file; then go to step 6 

6. Close both files 
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Sequential Line Input: An Example 

Using the line-oriented input, you can write programs that edit other basic 
program files: renumber them, change lprints to prints, etc. — as long as these 
"target" programs are stored in ascii format. 

The following program counts the number of lines in any ascii — format basic 
disk file with the extension /txt. 

10 CLEAR 300 

20 INPUT'WHAT IS THE NAME OF THE PROGRAM"; PROG* 

30 IF INSTR(PROG*»"/TXT")=0 THEN 110 'require /TXT extension 

40 0PEN"I H t 1 t PROG* 

50 H. = 

60 IF EOF(l) THEN 30 

70 n,= n,+ l: LINE INPUT#I t TEMP* 

80 GOTO G0 

30 PRINT PROG*" IS" 11 "LINES LONG*" 

100 CLOSE: GOTO 20 

110 PRINT "FILESPEC MUST INCLUDE THE EXTENSION '/TXT'" 

120 GOTO 20 

For basic programs stored in ascii, each program line ends with a carriage 
return character not preceded by a line feed. So the line input in line 70 
automatically reads one entire line at a time, into the variable temp$. Variable 
i% actually does the counting. 

To try out the program, first save any basic program using the a (ascii) option 
(See save). Use the extension /txt. 
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Random Access Techniques 

Random access offers several advantages over sequential access: 

• Instead of having to start reading at the beginning of a file, you can read any 
record you specify. 

• To update a file, you don't have to read in the entire file, update the data, and 
write it out again. You can rewrite or add to any record you choose, without 
having to go through any of the other records. 

• Random access is more efficient — data takes up less space and is read and 
written faster. 

• Opening a file for direct access allows you to write and read from the file via 
the same buffer. 

• Random access provides many powerful statements and functions to structure 
your data. Once you have set up the structure, direct input/output becomes 
quite simple. 

The last advantage listed above is also the "hard part" of direct access. It takes 
a little extra thought. 

For the purposes of direct access, you can think of a disk file as a set of boxes 
— like a wall of post-office boxes. Just like the post office receptacles, the file 
boxes are numbered. We call these boxes "records." 

You can place data in any record, or read the contents of any record, with 
statements like: 

PUT 1*5 write buffer- 1 contents to record 5 

GET 1 >5 read the contents of record 5 into buffer- 1 

In Figure 14, we assume a record length of 256. 



(256 ) 

[bytesJ 

#6 



(256 \ 

Kbytes,/ 

#1 



(256 ) 
\BYTES J 

#7 



/256 \ 
\BYTESy 

#2 



(256 ) 
\ BYTES J 

#8 



(256 \ 
MBYTES,/ 

#3 



( 256 ) 

[bytes J 

#9 



(256 \ 
[BYTES J 

#4 



(256 ) 
[BYTESJ 

#10 

l#5l 




RECORDS IN DISK FILE 
Figure 14. get and put. 



I/O BUFFERS IN RAM 
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The buffer is a waiting area for the data. Before writing data to a file, you must 
place it in the buffer assigned to the file. After reading data from a file, you 
must retrieve it from the buffer. 

As you can see from the sample put and get statements above, data is passed to 
and from the disk in records. The size of each record is determined by an Open 
statement. 

Storing Data in a Buffer 

You must place the entire record into the buffer before putting its contents into 
the disk file. 

This is accomplished by 1) dividing the buffer up into fields and naming them, 
then 2) placing the string or numeric data into the fields. 

For example, suppose we want to store a glossary on disk. Each record will 
consist of a word followed by its definition. We start with: 

100 0PEN"R"» It "GLOSSARY/BAS" 

110 FIELD It 16 AS ND$* 240 AS MEANINGS 

Line 100 opens a file named glossary/bas (creates it if it doesn't already exist); 
and gives buffer 1 direct access to the file. 

Line 110 defines two fields onto buffer 1: 

wd$ consists of the first 16 bytes of the buffer; 

meanings consists of the last 240 bytes. 

wd$ and meanings are now field-names 

What makes field names different? Most string variables point to an area in 
memory called the string space. This is where the value of the string is stored. 

Field names, on the other hand, point to the buffer area assigned in the field 
statement. So, for example, the statement: 

10 PRINT WD$? ":" 5 MEANING* 

displays the contents of the two buffer fields defined above. 

These values are meaningless unless we first place data in the buffer, lset, rset 
and get can all be used to accomplish this function. We'll start with lset and 
rset, which are used in preparation for disk output. 

Our first entry is the word "left-justify" followed by its definition. 

100 0PEN"R H * 1* "GLOSSARY/BAS" 

110 FIELD 1* IS AS ND$, 240 AS MEANING$ 

120 LSET WD*="LEFT-JUSTIFY" 

130 LSET MEANING*="T0 PLACE A VALUE IN A FIELD FROM LEFT TO 
RIGHT? IF THE DATA DOESN'T FILL THE FIELD* BLANKS ARE 
ADDED ON THE RIGHT 5 IF THE DATA IS TOO LONG t THE EXTRA 
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CHARACTERS ON THE RIGHT ARE IGNORED* LSET IS A LEFT- 
JUSTIFY FUNCTION/' 

Line 120 left-justifies the value in quotes into the first field in buffer 1. Line 130 
does the same thing to its quoted string. 

Note: rset would place filler-blanks to the left of the item. Truncation would 
still be on the right. 

Now that the data is in the buffer, we can write it to disk with a simple put 
statement: 

140 PUT 1 ,1 
150 CLOSE 

This writes the first record into the file glossary/bas. 

To read and print the first record in glossary/bas, use the following sequence: 

1S0 OPENTV" t it "GLOSSARY/BAS" 

170 FIELD It IS AS ND$ # 240 AS HEANING* 

180 GET 1 ,1 

1S0 PRINT MD$: PRINT MEANING* 

200 CLOSE 

Line 160 and 170 are required only because we closed the file in line 150. If we 
hadn't closed it, we could go directly to line 180. 
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Random Access: A General 
Procedure 

The previous example shows the necessary sequences to read and write using 
random access. But it does not demonstrate the primary advantages of this form 
of access — in particular, it doesn't show how to update existing files by going 
directly to the desired record. 

The program below, gloss acc/b as, develops the glossary example to show 
some of the techniques of random access for file maintenance. But before 
looking at the program, study this general procedure for creating and 
maintaining files via random access. 



Step 


See GLOSSACC/BAS, 
Line Number 


1 . Open the file 

2. Field the buffer 

3. Get the record to be updated 

4. Display current contents of the record (use 
CVD, CVI, CVS before displaying numeric 
data) 

5. LSET and RSET new values into the fields 
(use MKD$, MKI$, MKS$ with numeric data 
before setting it into the buffer) 

6. PUT the updated record 

7. To update another record, continue at step 3. 
Otherwise, go to step 8. 

8. Close the file 


110 

120 

140 

145-170 

210-230 

240 
250-260 

270 



10 REM 


100 


CLS : 


110 


OPEN " 


120 


FIELD 


130 


INPUT 


U0 


GET 1 * 


145 


HX'l = 


150 


PRINT 


1G0 


PRINT 


170 


PRINT 


180 


m = " 




W$ 


190 


0$ = » 




OK?" : 


200 


INPUT 


210 


IF m 


220 


IF D$ 



... GLOSSACC/BAS ... 

CLEAR 300 

R" . 1 > "GL0SSARY/BAS" 

1» IS AS WD*» 238 AS MEANING*. 2 AS NX* 

"WHAT RECORD DO YOU WANT TO ACCESS"! RX 

CVHNX*) 'SAVE LINK TO NEXT ALPHABETICAL ENTRY 

"WORD : "WD* 

"DEF'N : " : PRINT MEANING* 

"NEXT ALPHABETICAL ENTRY: RECORD *:" NXX : PRINT 

" : INPUT "TYPE NEW WORD <ENTER> OR <ENTER> IF OK " 5 

" : PRINT "TYPE NEW DEF'N < ENTER) OR < ENTER) IF 
LINE INPUT D$ 
"TYPE NEW SEQUENCE NUMBER OR <ENTER> IF OK" 5 NX* 
<> "" THEN LSET WD* = W* 
<> "" THEN LSET MEANING* = D* 



./-" 
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230 LSET NX$ = MKI$ (HX1) 

240 PUT i t R% 

245 RX = NX* 'USE NEXT ALPHA* LINK AS DEFAULT FOR NEXT RECORD 

250 CLS : PRINT n TYPE <ENTER> TO READ NEXT ALPHA* ENTRY,": 

PRINT" OR RECORD # <EIMTER> FOR SPECIFIC ENTRY,": INPUT " 

OR < ENTER) TO QUIT'S RX 
2S0 IF 0<RX THEN 140 
270 CLOSE 
280 END 

Notice we've added a field, nx$, to the record (line 120). nx$ will contain the 
number of the record which comes next in alphabetical sequence. This enables 
us to proceed alphabetically through the glossary, provided we know which 
record contains the entry which should come first. 

For example, suppose the glossary contains: 



record# 


word (WD$) 


defn, 


pointer to next 
alpha, entry (NX$) 


1 
2 
3 
4 


LEFT-JUSTIFY 
BYTE 

RIGHT-JUSTIFY 
HEXADECIMAL 




3 
4 

1 



When we read record 2 (byte), it tells us that record 4 (hexadecimal) is next, 
which then tells us record 1 (left- justify) is next, etc. The last entry, record 3 
(right- justify), points us to zero, which we take to mean "The End." 

Since nx$ will contain an integer, we have to first convert that number to a two- 
byte string representation, using mki$ (line 230 above). 

The following program displays the glossary in alphabetical sequence: 

300 REM ♦♦♦ GL0SS0UT/BAS ♦♦« 

310 CLS s CLEAR 300 

320 OPEN "R" > 1* "GLOSSARY/BAB" 

330 FIELD 1* IB AS ND$ * 238 AS MEANING*, 2 AS NX* 

340 INPUT "WHICH RECORD IS FIRST ALPHABETICALLY" 5 HI 

350 GET 1 t HI 

3S0 PRINT : PRINT WD* 

370 PRINT MEANING* 

380 HI = CUI(NX$) 

39-0 INPUT "PRESS <EIMTER> TO CONTINUE" 5 X 

400 IF HI <> THEN 350 

410 CLOSE 

420 END 
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Disk BASIC Error Codes/Messages 

51 Field overflow 

52 Internal error 

53 Bad file number 

54 File not found 

55 Bad file mode 
58 Disk i/o error 

62 Disk full 

63 Input past end 

64 Bad record number 

65 Bad file name 

67 Direct statement in file 

68 Too many files 

69 Disk write-protect 

70 File access 

Note: Disk errors cannot be simulated via the error statement. 
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FIELD 134-6 
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INIT 78 
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PRINT # 131-3 

Printer .31, 47, 105 

Programming ii, 1 1 

PROT 10,25,57 
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READ 70 
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Number of 45, 77 

Physical 77 
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Using • 20 
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Radio Shack Software License 

The following are the terms and conditions of the Radio Shaek Software L.cense for 
copies of Radio Shack software either purchased by the customer, or received with 
or as part ot hardware purchased by customer: 

A. Radio Shack grants to CUSTOMER a personal, non-exclusive. pa,d up license to 
use the Radio Shack computer software programs received. Title to the media 
on which the software is recorded (cassette and/or disk) or stored (ROM) is 
transferred to the CUSTOMER, but not title to the software. 

B. In consideration for this license. CUSTOMER shall not reproduce cop.es of such 
software programs except to produce the number of copies required for 
personal use by CUSTOMER (if the software allows a backup copv to be made) 
and to include Radio Shack's copyright notice on all copies of programs 
reproduced in whole or in part. 

C. CUSTOMER may resell Radio Shack's system and applications software 
(modified or not. in whole or in part), provided CUSTOMER has purchased one 
copy of the software for each one resold. The provisions of this Software 
License (paragraphs A, B. and C) shall also be applicable to third parties 
purchasing such software from CUSTOMER. 



Important Note 



AH Radio Shack computer programs are licensed on an "as is" basis without 
warranty. 

Radio Shack shall have no liability or responsibility to customer or any other person 
or entity wtth respect to any liability, loss or damage caused or alleged to be caused 
directly or indirectly by computer equipment or programs sold by Radio Shack 
including but not limited to any interruption of service, loss of business or 
anticipatory profits or consequential damages resulting from the use or operation of 
such computer or computer programs . 

Good data processing procedure dictates that the user test the program, run and test 
sample sets of data, and run the system in parallel with the system previously , n use 
for a period of time adequate to insure that results of operation of the compuier or 
program are satisfactory. 
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Service Policy 

Radio Shack's nationwide network of service facilities provides quick, convenient, 
and reliable repair services for all of its computer products, in most instances. 
Warranty service will be performed in accordance with Radio Shack's Limited 
Warranty. Non-warranty service will be provided at reasonable parts and labor 
costs. 

Because of the sensitivity of computer equipment, and the problems which can 
result from improper servicing, the following limitations also apply to the services 
offered by Radio Shack: 

1 . If any of the warranty seals on any Radio Shack computer products are broken, 
Radio Shack reserves the right to refuse to service the equipment or to void any 
remaining warranty on the equipment. 

2. If any Radio Shack computer equipment has been modified so that it is not 
within manufacturer's specifications, including, but not limited to, the 
installation of any non-Radio Shack parts , components , or replacement boards , 
then Radio Shack reserves the right to refuse to service the equipment, void any 
remaining warranty, remove and replace any non-Radio Shack part found in the 
equipment, and perform whatever modifications are necessary to return the 
equipment to original factory manufacturer's specifications. 

3 . The cost for the labor and parts required to return the Radio Shack computer 
equipment to original manufacturer's specifications will be charged to the 
customer in addition to the normal repair charge . 
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IMPORTANT NOTICE 

ALL RADIO SHACK COMPUTER PROGRAMS ARE LICENSED ON AN 
"AS IS" BASIS WITHOUT WARRANTY. 

Radio Shack shall have no liability or responsibility to customer or any 
other person or entity with respect to any liability, loss or damage caused 
or alleged to be caused directly or indirectly by computer equipment or 
programs sold by Radio Shack, including but not limited toany interrup- 
tion of service, loss of business or anticipatory profits or consequential 
damages resulting from the use or operation of such computer or 
computer programs. 

NOTE: Good data processing procedure dictates that the user test the 
program, run and test sample sets of data, and run the system in 
parallel with the system previously in use for a period of time 
adequate to insure that results of operation of the computer or 
program are satisfactory. 

RADIO SHACK SOFTWARE LICENSE 

A. Radio Shack grants to CUSTOMER a non-exclusive, paid up license to 
use on CUSTOMER'S computer the Radio Shack computer software 
received. Title to the media on which the software is recorded (cassette 
and/or disk) or stored (ROM) is transferred to the CUSTOMER, but not 
title to the software. 

B. In consideration for this license, CUSTOMER shall not reproduce 
copies of Radio Shack software except to reproduce the number of copies 
required for use on CUSTOMER'S computer (if the software allows a 
backup copy to be made), and shall include Radio Shack's copyright 
notice on all copies of software reproduced in whole or in part. 

C. CUSTOMER may resell Radio Shack's system and applications soft- 
ware (modified or not, in whole or in part), provided CUSTOMER has 
purchased one copy of the software for each one resold. The provisions 
of this software License (paragraphs A, B, and C) shall also be applicable 
to third parties purchasing such software from CUSTOMER. 
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LIMITED WARRANTY 

For a period of 90 days from the date of delivery, Radio Shack warrants to the 
original purchaser that the computer hardware unit shall be free from manufac- 
turing defects. This warranty is only applicable to the original purchaser who 
purchased the unit from Radio Shack company-owned retail outlets or duly 
authorized Radio Shack franchisees and dealers. This warranty is voided if the 
unit is sold or transferred by purchaser to a third party. This warranty shall be 
void if this unit's case or cabinet is opened, if the unit has been subjected to 
improper or abnormal use, or if the unit is altered or modified. If a defect occurs 
during the warranty period, the unit must be returned to a Radio Shack store, 
franchisee, or dealer for repair, along with the sales ticket or lease agreement! 
Purchaser's sole and exclusive remedy in the event of defect is limited to the 
correction of the defect by adjustment, repair, replacement, or complete 
refund at Radio Shack's election and sole expense. Radio Shack shall have no 
obligation to replace or repair expendable items. 

Any statements made by Radio Shack and its employees, including but not 
limited to, statements regarding capacity, suitability for use, or performance of 
the unit shall not be deemed a warranty or representation by Radio Shack for 
any purpose, nor give rise to any liability or obligation of Radio Shack. 

EXCEPT AS SPECIFICALLY PROVIDED IN THIS WARRANTY OR IN THE 
RADIO SHACK COMPUTER SALES AGREEMENT, THERE ARE NO 
OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT 
LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 
FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL RADIO 
SHACK BE LIABLE FOR LOSS OF PROFITS OR BENEFITS, INDIRECT 
SPECIAL, CONSEQUENTIAL OR OTHER SIMILAR DAMAGES ARISING 
OUT OF ANY BREACH OF THIS WARRANTY OR OTHERWISE. 
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